# Foundation MVP

> Build and deploy apps with auth, billing, data, AI, and integrations — configured, not coded.

## Agent Views

- Foundation App Builder: https://docs.foundationmvp.com/agents/foundation-app-builder.md
- Foundation Deploy Contract: https://docs.foundationmvp.com/agents/foundation-deploy-contract.md
- Foundation SDK Reference: https://docs.foundationmvp.com/agents/foundation-sdk-reference.md
- Page Contract: https://docs.foundationmvp.com/agents/page-contract.md

---

# Foundation App Builder

Canonical agent workflow for frontend apps that consume the Foundation backend through `foundation-sdk`.

Last updated: 2026-06-29

## Use This When

- Creating a new Foundation-backed web app.
- Adding Foundation SDK integration to an existing React, Vue, Svelte, Next, or plain web app.
- Adding Foundation-backed features such as auth, database CRUD, files, integrations, account screens, OAuth consent, or config-driven UI.
- Reviewing a consumer app before Foundation deployment.

## Required References

- SDK reference: https://docs.foundationmvp.com/agents/foundation-sdk-reference.md
- Deploy contract: https://docs.foundationmvp.com/agents/foundation-deploy-contract.md
- Full docs bundle: https://docs.foundationmvp.com/llms-full.txt

## Workflow

Classify the request first:

- New app: create or adapt a frontend app that consumes Foundation.
- Existing app: add Foundation SDK initialization, auth, services, or deployment files without rewriting unrelated code.
- Feature: add one Foundation-backed workflow to an app that already has SDK initialization.
- Review: audit SDK usage and deploy readiness.

## New App Or Retrofit

1. Inspect the existing repo before editing. Preserve framework, routing, styling, and state-management conventions.
2. Install `foundation-sdk` plus the selected auth peer: `aws-amplify` for Cognito or `@auth0/auth0-spa-js` for Auth0.
3. Create one SDK initialization module or provider. Await `createFoundation(...)` once and share the instance through app context/state.
4. Support local development with explicit `configUrl`, `tenantId`, `appId`, and optional dev-only `baseUrl`.
5. Support production by allowing `createFoundation({ auth })` to read `/foundation-env.json`.
6. Implement login, registration, auth callback, logout, and guarded routes as requested.
7. Build the requested core workflow with `foundation.db`, `foundation.files`, `foundation.integration`, `foundation.account`, `foundation.oauth`, `foundation.config`, or `foundation.log`.
8. Add `mvp.config.json` at the app repo root and verify its output directory and entry file.
9. Run available typecheck, lint, tests, and build scripts.

## Feature Additions

Reuse the existing Foundation instance. Do not introduce a second `createFoundation()` call.

Keep service calls in the app's established data layer, hook, store, or route loader pattern. Add loading, empty, success, and error states. Handle unauthenticated users before calling authenticated services.

Use pagination for lists that can grow, compute `sha256` before file upload, refresh integration status after connect/disconnect, and respect `foundation.config` for backend-provided theme, features, plans, connectors, and resources.

## Review Mode

Use a code-review stance. Lead with findings ordered by severity and include file/line references.

Prioritize:

- Missing or invalid `mvp.config.json`.
- Build output mismatch with `files` or `entry`.
- Missing SDK or auth peer dependency.
- Wrong auth provider entry point.
- Un-awaited or duplicated SDK initialization.
- Production code that depends on dev-only `baseUrl`.
- Sign-in or sign-up flows that ignore result objects.
- Missing hosted-login callback handling.
- Unguarded authenticated routes.
- File uploads without `sha256`.
- Integration flows that only handle one connect response shape.
- Frontend secrets or hardcoded user tokens.

If no major issues are found, say so and list remaining test gaps or backend assumptions.

## Default `mvp.config.json`

```json
{
  "build": "npm install && npm run build",
  "files": "dist",
  "entry": "index.html",
  "sdk": "^1.0.0"
}
```

Adjust `files` and `entry` only when the chosen framework uses a different build output.

## Starter User Prompt

```text
Use https://docs.foundationmvp.com/agents/foundation-app-builder.md to build a production-ready frontend app that consumes the Foundation backend.

App goal:
Framework and router:
Styling system:
Auth provider: Cognito or Auth0
Foundation config URL for local development:
Foundation tenant ID for local development:
Foundation app ID for local development:
Optional local API proxy base URL:
Entities to use through foundation.db:
File workflows to support through foundation.files:
Integrations to support through foundation.integration:
Account/profile fields:
Deployment output directory:
Deployment entry file:
```

---

# Foundation Deploy Contract For Agents

Canonical deployment reference for Foundation consumer app repositories.

Last updated: 2026-06-29

## Required File

Consumer app repositories need `mvp.config.json` at the repo root.

Default:

```json
{
  "build": "npm install && npm run build",
  "files": "dist",
  "entry": "index.html",
  "sdk": "^1.0.0"
}
```

Fields:

- `build`: command Foundation runs before deployment.
- `files`: build output directory to upload.
- `entry`: app entry file inside `files`.
- `sdk`: SDK compatibility hint.
- `node`: optional Node major version.

## Deployment Flow

Foundation reads `mvp.config.json` from GitHub, downloads the repo, runs the build command, uploads the configured output directory, and writes `/foundation-env.json` next to the built assets.

The app should not create `/foundation-env.json` itself for production deployment. Foundation writes it.

## Runtime Identity

`foundation-env.json` contains runtime identity:

```json
{
  "applicationId": "app-id",
  "applicationTenant": "tenant-id",
  "applicationVersion": "1.0.0",
  "configUrl": "https://backend.example.com/api/v1/public/init"
}
```

The SDK reads this file automatically in production. When it is present, values from the file override local options and `baseUrl` is cleared.

## Local Development

Local development should pass explicit SDK config:

```ts
await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL,
  auth
})
```

`baseUrl` is optional and dev-only. Use it for local proxies to avoid CORS while developing against a remote backend.

## Verification Checklist

- `mvp.config.json` exists at the repo root.
- `mvp.config.json` has `build`, `files`, and `entry`.
- The configured `build` command succeeds.
- The configured `files` directory exists after build.
- The configured `entry` file exists inside `files`.
- SDK initialization works with explicit local config.
- Production code can initialize from `/foundation-env.json`.
- Production code does not require `baseUrl`.
- Built frontend assets do not include private secrets or service credentials.

---

# Foundation SDK Reference For Agents

Canonical integration reference for apps that use `foundation-sdk`.

Last updated: 2026-06-29

## Install

```bash
npm install foundation-sdk
npm install aws-amplify
```

Use `aws-amplify` only for Cognito apps. For Auth0 apps, install `@auth0/auth0-spa-js` instead.

## Initialize

Cognito:

```ts
import { createFoundation } from 'foundation-sdk'
import { cognitoAuth } from 'foundation-sdk/cognito'

const foundation = await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL,
  auth: cognitoAuth
})
```

Auth0:

```ts
import { createFoundation } from 'foundation-sdk'
import { auth0Auth } from 'foundation-sdk/auth0'

const foundation = await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL,
  auth: auth0Auth
})
```

Production may omit identity values:

```ts
const foundation = await createFoundation({ auth: cognitoAuth })
```

`/foundation-env.json` overrides `configUrl`, `tenantId`, `appId`, and clears `baseUrl`.

## Critical Rules

1. Always await `createFoundation(...)`.
2. Initialize the SDK once and share it through app context/state.
3. Use exactly one auth provider entry point unless building separate variants.
4. Do not put private secrets in frontend code.
5. Set `window.__foundation = foundation` only when using `foundation-sdk/components`.
6. Treat `baseUrl` as dev-only.

## Auth

Available methods:

```ts
foundation.auth.user
foundation.auth.isAuthenticated
foundation.auth.getToken()
foundation.auth.login(options?)
foundation.auth.logout(options?)
foundation.auth.handleCallback(url?)
foundation.auth.signIn(email, password)
foundation.auth.signUp(email, password, metadata?)
foundation.auth.confirmSignUp(email, code)
foundation.auth.resendSignUpCode(email)
foundation.auth.forgotPassword(email)
foundation.auth.resetPassword(code, newPassword)
foundation.auth.onChange(callback)
```

Sign-in pattern:

```ts
const result = await foundation.auth.signIn(email, password)
if (result.isSignedIn) {
  router.push('/dashboard')
} else if (result.nextStep?.signInStep === 'CONFIRM_SIGN_UP') {
  router.push({ path: '/confirm', query: { email } })
}
```

Sign-up pattern:

```ts
const result = await foundation.auth.signUp(email, password, { name })
if (result.isSignUpComplete) {
  showCheckEmail()
} else if (result.nextStep?.signUpStep === 'CONFIRM_SIGN_UP') {
  showCodeConfirmation()
}
```

Call `foundation.auth.handleCallback()` on hosted-login callback routes. Subscribe with `foundation.auth.onChange()` or refresh auth state after login, logout, callback, and registration.

## Database

```ts
foundation.db.list<T>(entity, options?)
foundation.db.get<T>(entity, id)
foundation.db.create<T>(entity, data)
foundation.db.update<T>(entity, id, updates)
foundation.db.save<T>(entity, data)
foundation.db.delete(entity, id)
```

List options:

```ts
{
  filters?: Record<string, unknown>
  limit?: number
  cursor?: string
  orderBy?: string
  orderDir?: 'asc' | 'desc'
}
```

Paginated list:

```ts
let cursor: string | undefined
const all = []

do {
  const { items, nextCursor } = await foundation.db.list('projects', {
    limit: 50,
    cursor
  })
  all.push(...items)
  cursor = nextCursor
} while (cursor)
```

## Files

```ts
foundation.files.upload({ name, contentType, file, sha256 })
foundation.files.initiate({ name, contentType, contentLength, sha256, metadata? })
foundation.files.get(fileId)
foundation.files.delete(fileId)
foundation.files.list({ limit?, cursor? }?)
```

Compute SHA-256 before upload:

```ts
const result = await foundation.files.upload({
  name: file.name,
  contentType: file.type,
  file,
  sha256
})
```

Use `initiate` only when the app needs manual control of the signed upload.

## Integrations

```ts
foundation.integration.all()
foundation.integration.list()
foundation.integration.connections()
foundation.integration.status(source)
foundation.integration.connect(source)
foundation.integration.disconnect(source, configurationId)
```

Use `foundation.integration.all()` for catalog plus current connection state.

Use `foundation.integration.connect(source)`. If the result includes a `url`, open a popup or redirect and refresh connection status after completion. Also handle immediate success/configuration responses.

Use `disconnect(source, configurationId)` only after clear user confirmation.

## Account

```ts
foundation.account.get<TUser, TAccount>()
foundation.account.update(data)
foundation.account.usage()
foundation.account.resendVerification()
```

## OAuth Consent

For apps acting as OAuth authorization servers:

```ts
const client = await foundation.oauth.getClient(clientId)
const { code } = await foundation.oauth.authorizeConsent({
  client_id,
  redirect_uri,
  scope,
  state,
  code_challenge,
  code_challenge_method
})
```

Only call `authorizeConsent` after explicit user approval, then redirect back with `code` and `state`.

## Config

```ts
foundation.config.app
foundation.config.features
foundation.config.plans
foundation.config.theme
foundation.config.connectors
foundation.config.resources
foundation.config.auth
foundation.config.raw
```

Use backend config to hide unavailable UI and apply theme or plan-aware behavior.

## Logging

```ts
foundation.log.info(message, context?)
foundation.log.warn(message, context?)
foundation.log.error(message, context?)
foundation.log.event(eventName, data?)
```

Logging is fire-and-forget. Do not block UI on logging.

## Web Components

```ts
import 'foundation-sdk/components'
;(window as any).__foundation = foundation
```

```html
<foundation-connect integration-id="github-oauth"></foundation-connect>
```

Events: `success`, `error`, `close`.

For Vue, configure `isCustomElement` for `foundation-*` tags.

---

# Foundation Docs Page Contract

How feature documentation is structured, so humans and agents can navigate it predictably.

Last updated: 2026-06-29

## Why This Exists

Every platform feature page (`/platform/*`) follows a fixed section structure. Because the structure is fixed, an agent can fetch the page's raw Markdown twin and reliably locate a section by a heading it already knows — no per-page guessing.

Each rendered page is also available as raw Markdown by appending `.md` to its path:

```text
https://docs.foundationmvp.com/platform/billing       (HTML, for humans)
https://docs.foundationmvp.com/platform/billing.md     (Markdown, for agents)
```

## Required Sections

Every feature page has these H2 headings, in this order:

```markdown
## Configure        — set the feature up on the platform. No code. Reads for non-developers.
## Use in your app  — wire the feature into a frontend built on foundation-sdk. Real SDK calls.
## Reference        — thin list of links to deeper references (SDK, API, related features).
```

Feature-specific H2s may appear between `Configure` and `Reference`, but the three above are always present and always in this order.

## Anchors Are Predictable

Heading slugs follow the GitHub algorithm: lowercase, spaces to hyphens, punctuation dropped. The same slug is used for the HTML anchor and the Markdown heading, so:

- `## Use in your app` → anchor `#use-in-your-app` (in both surfaces)
- An agent can split a fetched `.md` on lines matching `^## ` and select a block by its known heading.

A URL fragment (`...billing.md#use-in-your-app`) is **not** sent to the server — fetching always returns the whole file. "Hop to a section" means: fetch the page, then seek the known heading. For section-level *retrieval* (just one block returned), use the MCP `get_docs` tool, which slices the same source on this contract.

## Authoring Rules

1. Pure Markdown only — no VitePress containers (`:::tip`), no `<script>`, no Vue. This keeps the `.md` twin byte-identical to clean Markdown.
2. `Use in your app` examples must use real `foundation-sdk` methods. See [the SDK reference](/agents/foundation-sdk-reference.md). Do not invent methods; mark app-specific field names as such.
3. Keep `Reference` thin — link out, don't restate.
4. Do not duplicate cross-cutting SDK/API detail per feature; link to the shared reference instead.

## Formatting — scannable for both readers

Use structure that renders well for humans **and** stays clean Markdown for agents. Rule of thumb:
prefer formatting **both** surfaces benefit from; reject presentation-only formatting that helps one
reader and muddies the twin.

- **Sequences → numbered steps.** A setup flow is `### 1.` / `### 2.` … so it reads as a flow and the
  steps appear in the page outline.
- **Choices & comparisons → tables.** Either/or decisions (this vs that, plan tiers) become a small
  table with a *Best when* / *What happens* column — not lookalike bullet lists.
- **Key callouts → blockquotes (`>`).** One-line reassurances or warnings stand apart from the steps.
- **No human-only formatting.** No color callout containers (`:::tip` / `:::warning`), cards, badges,
  or tabs. They render for a human but pollute or vanish in the `.md` twin — one reader, not both.
  Tables, steps, and blockquotes are semantic Markdown: humans get the visual structure, agents get
  clean text.

## Human-only asides

Sometimes a non-dev needs context an agent doesn't — "what is Stripe and why you need it." Wrap it:

```markdown
<!--human-->
> **New to Stripe?** Stripe processes the payment — takes the card, charges it, pays you out.
<!--/human-->
```

The build renders the block for humans (HTML comments are invisible); the `.md` twin and
`llms-full.txt` strip it. Use sparingly — this is the one place the two surfaces legitimately differ.
It is for *explanatory* context only; never put steps, decisions, or anything an agent needs to build
inside a human-only block.

## "Use in your app" — no-code first

Most users don't write code; **their agent does**. So this section leads with the plain-language
direction a human gives their agent, and tucks the code behind a collapse so a non-dev is never met
with a wall of code:

````markdown
**Tell your agent:** "Show an upgrade prompt when someone hits their plan limit."

<details>
<summary>Show the code</summary>

```ts
// real foundation-sdk calls
```

</details>
````

- A non-dev sees the intent; the code is collapsed by default.
- A developer expands it; the **agent reads the code from the twin regardless**.
- The generator unwraps `<details>`/`<summary>`, so the twin is clean code — the bot never sees the
  collapse. **Keep one blank line after `<summary>` and before `</details>`** or the code won't render.

---

# What is Foundation

Foundation is the backend your app needs — users, payments, data, AI, integrations — already built and
running. You build the part that's actually yours; Foundation handles the hard infrastructure
underneath so you never have to.

## Skip the infrastructure

Every app needs the same hard, boring groundwork: logging people in, storing data, taking payments,
exposing an API, and running it all reliably. It takes months and a team to build — and it's nearly
identical every time.

Foundation gives you all of it, ready to go. You don't build auth, a database, billing, or deployment.
You turn them on and configure them, and spend your time on what makes your app *different*.

## You bring the app. Foundation brings the backend.

- **Your app** — the interface your users see and the experience that makes it yours. Build your own
  UI, or start from ours.
- **Foundation's backend** — users, payments, data, files, AI, integrations, and an API — configured,
  not coded, and wired together for you.

Your frontend talks to that backend through a connector and SDK Foundation provides: login, data,
payments, and integrations are already there. You write what's unique to your app, not the plumbing.

> Building an API service or an MCP server with no UI at all? That works too — skip the frontend and
> just use the endpoints.

## You decide. Your agent builds.

You don't have to write the frontend by hand, either:

- **You're the director.** You decide what your app should do and how it should feel. You don't need to
  know how the backend pieces fit together — Foundation does, and these docs hand that knowledge to
  your agent.
- **Your agent is the builder.** An AI agent — our wizard, Claude Desktop, or your own — configures the
  backend and builds your app against it, using the SDK and components Foundation provides.

You bring the idea. Foundation brings the backend. Your agent does the assembly.

## Turn on only what you need

The backend is modular — every app starts simple and adds capabilities:

| Capability | What it gives your app |
|---|---|
| **Users & accounts** | Login, registration, profiles |
| **Payments** | Subscriptions and plans (via [Stripe billing](/platform/billing)) |
| **Data** | Your own database, files, and storage |
| **AI** | Prompts and actions wired to your data |
| **Integrations** | Connect outside services — Stripe, Slack, Google, and more |
| **API & MCP server** | Your app can be used by other apps and AI agents |

Not every app needs all of these. An API service might skip users entirely; a membership site leans on
users and payments. You choose.

## Two jobs: configure, then build

1. **Configure** — set up the backend: what your app does, who can use it, what it charges. No code —
   done in the dashboard, by talking to the wizard, or through Claude.
2. **Build** — build your app's experience on top of it: your UI (or ours), wired to the backend with
   Foundation's SDK and components.

The rest of these docs follow that split. The **Configure** section covers setting things up; the
**Build** section covers making the app.

## Three ways to do it

You're never locked into one way to work:

- **Dashboard** — click through and configure visually.
- **Wizard** — describe what you want in plain language; our AI configures it.
- **Claude Desktop / MCP** — do everything through conversation. No UI needed.

See [Three ways to build & manage](/understand/three-ways-to-build) for how each works, or jump to the
[Quickstart](/guide/quickstart).

---

# How an app fits together

A Foundation app is a set of parts that snap together. You turn on the ones you need; Foundation
connects them and runs them. This page is the mental model — once it clicks, the rest of the docs are
just detail.

## It's all configuration

Every app is defined by configuration, not code:

- **Which capabilities are on** — users, billing, data, AI, integrations
- **How each is set up** — your auth method, your plans, your data models
- **What's exposed** — REST API, MCP, API-as-a-service (a switch per capability)
- **Who can do what** — roles and scopes, across everything

You set that config however you like — the result is identical.

## The kernel, and the parts you add

Every app — even a tiny one — comes with a **kernel**:

- It deploys and runs (shared or dedicated infrastructure)
- It has an API surface (REST + MCP, off by default, flipped on per capability)
- It has a roles & scopes engine that governs access to everything
- It can have a custom domain and SSL

On top of the kernel you switch on **capabilities** as needed:

| Capability | What it adds |
|---|---|
| Identity | Login, registration, OAuth, API keys |
| Data | Entities (a database), file storage |
| Monetization | Stripe, plans, usage limits, gating |
| AI | Prompts and actions, wired to your data |
| Integrations | Connect outside services as tools |

## How the parts connect

The power is in how the parts reference each other — this is the glue Foundation handles so you don't
have to:

- **Plans gate capabilities.** A billing plan maps to usage limits, so "Pro unlocks AI" just works.
- **Entities power actions.** Your AI prompts and actions can read and write your data.
- **Integrations become tools.** A connected service's methods can be called by your actions, your
  API, or an AI agent.
- **Roles & scopes cut across all of it.** One permission model decides who — and which bots — can
  touch each entity, action, and integration.

You don't wire these together by hand. You turn things on; Foundation connects them.

## What you get when you deploy

Deploying provisions the real infrastructure behind those capabilities:

| You configured | You get |
|---|---|
| Users | Auth (Cognito or Auth0), user pools, OAuth |
| Data | A database for your entities, plus file storage |
| Billing | A live Stripe connection and plan management |
| API | REST endpoints and an MCP server |
| Domain | A custom domain with automatic SSL |

## Shared or dedicated

| | What it is | Best for |
|---|---|---|
| **Shared** | Runs on Foundation's shared infrastructure | Getting started — fast and cheap |
| **Dedicated** | Your own isolated infrastructure, domain, and auth | Production and businesses |

These are points on a spectrum, not rival choices — start shared and move to dedicated when you're
ready.

## Apps can have apps

A Foundation app can spawn **child apps** that share the parent's resources — the basis for
marketplaces, plugin ecosystems, and multi-tenant platforms. More on this when you need it.

Next: [Three ways to build & manage](/understand/three-ways-to-build).

---

# Three ways to build & manage

Everything in Foundation is configuration — so there are several ways to set that configuration, and
they all hit the same backend. Pick whichever fits you; mix and match anytime.

## The three surfaces

| Way | What it's like | Best for |
|---|---|---|
| **Dashboard** | Click through and configure visually | Fine-tuning specific settings |
| **Wizard** | Describe what you want; an AI agent configures it | Initial setup and big changes |
| **Claude Desktop / MCP** | Pure conversation, no UI at all | Doing it all by chat — great for non-devs |

These aren't different products — they're three doors into the same config. Set billing in the
dashboard, then change a plan by telling Claude; it's the same app.

## The Wizard

The wizard is an AI agent built into Foundation. You describe what you want, it asks clarifying
questions, and it sets your app up.

> **You:** "An app where photographers upload portfolios and clients pay for premium access."
>
> **Wizard:** sets up user accounts (photographer + client roles), file storage for uploads, a free
> and a premium billing tier, entities for portfolios and galleries, and scoped access.
>
> **You:** "Deploy it." → Done.

Anything you can do in the dashboard, the wizard can do through conversation.

## Claude Desktop (or any MCP client)

Every Foundation app is an MCP server, so you can manage it from Claude Desktop — no browser.

1. Copy your MCP connection URL and token from your account.
2. Add it to Claude Desktop's MCP settings.
3. Start talking.

```
"Create an app called BookClub with user accounts."
"Add an entity called Books with title, author, and rating."
"Enable billing with a free plan and a $10/month premium plan."
"Deploy it."
```

You manage it the same way after launch:

```
"Show me users who signed up this week."
"Change the premium plan to $15/month."
"Who's connected to my API?"
```

### Sharing access

Through scoped permissions, you can let *other people's* agents into your app:

```
"Let Sarah's agent read the Books entity."
"Create a public scope that exposes the book catalog."
```

Any AI agent that speaks MCP can interact with your app — within the permissions you set.

## Which should you use?

- Non-dev, starting out → **Wizard** or **Claude Desktop**. Describe, don't configure.
- Want visual control → **Dashboard**.
- Live in your terminal or an agent → **Claude Desktop / MCP**.

No wrong answer, no lock-in. Next: [Configure vs Build](/understand/configure-vs-build).

---

# Configure vs build

Working with Foundation has two jobs, and it helps to keep them straight. One sets up the backend; the
other turns it into an app people use.

## Configure — set up the backend

Configuring is deciding what your app *is*: which capabilities are on, how they're set, who can use
them, what it charges. It's no-code — done in the dashboard, with the wizard, or through Claude.

This is the **[Configure](/platform/apps)** section of these docs — Branding, Authentication, Billing,
Data, and so on. Each page tells you what to decide and what each choice means.

## Build — make the app

Building is turning the configured backend into a running application: a frontend (or another app, or
an agent) that uses what you set up — the endpoints, the auth, and the components Foundation provides.

Here's the part that matters if you're not a developer: **you don't build it by hand — your agent
does.** You say what you want; your agent uses the Foundation SDK to assemble it. The Build section is
written for exactly that — plain-language directions up front, the exact code underneath.

## How they hand off

```
You decide  →  Configure the backend  →  Your agent builds the app  →  Deploy
(director)      (any of the three ways)    (using what you configured)
```

The same split shows up on every feature page:

- **Configure** — the decisions you make (director).
- **Use in your app** — how your agent builds with it (builder).

So a single page like [Billing](/platform/billing) covers both: set up your plans, then have your
agent wire them in.

Next: [Managing vs running](/understand/managing-vs-running).

---

# Managing vs running

Foundation apps involve two different API surfaces, and mixing them up causes a lot of confusion. Keep
them separate.

## The management surface — how you configure the app

This is how *you* (or your agent) set the app up: the dashboard, the MCP management tools, and a REST
management API. Same configuration underneath, three ways in. "Enable billing," "add an entity,"
"deploy" — all happen here.

## The runtime surface — what your app exposes

This is what your *finished app* offers to *its own* users and their agents: the REST endpoints and
MCP server for your entities, actions, and integrations. "List the books," "create an order," "charge
this customer" — your app's runtime API, used by the app you built and anyone you grant access.

## Why it matters

| | Management surface | Runtime surface |
|---|---|---|
| Who uses it | You / your building agent | Your app + its users & their agents |
| What it does | Configures the app | Runs the app's features |
| Examples | "Enable billing," "add an entity" | "List books," "create an order" |

So "configure via REST" (you setting up the app) is a completely different thing from "your app has a
REST API" (what you expose to your users). When a doc says *API*, check which one it means — these docs
always make it clear.

That's the whole mental model. From here, pick a capability in [Configure](/platform/apps), or jump to
the [Quickstart](/guide/quickstart).

---

# Quickstart

Get your first app running in minutes.

## 1. Create an Account

Sign up at [foundationmvp.com](https://foundationmvp.com).

## 2. Create Your App

You have three options:

### Option A: Talk to the Wizard
Describe what you want to build. The wizard asks questions, configures your app, and gets you to deploy.

### Option B: Use the Dashboard
Create a new app and walk through the settings: branding, users, billing, data, and more.

### Option C: Use Claude Desktop
Copy your MCP connection URL from your account, add it to Claude Desktop, and start building through conversation:

```
"Create a new app called My Project with user accounts and billing."
```

## 3. Configure Your App

Depending on what you're building, you'll set up some combination of:

- **Users** — enable login/registration, choose auth provider
- **Data** — define what your app tracks (entities)
- **Billing** — connect Stripe, define plans and limits
- **AI** — add prompts, chains, and tools
- **Integrations** — connect external services

## 4. Deploy

Hit deploy. Your app is live with a real backend — auth, database, APIs, everything.

## 5. Connect Your Frontend (Optional)

Bring your own UI and connect it using our frontend connector, or use the built-in UI components for login, registration, and settings.

[Next: How an App Fits Together →](/understand/how-an-app-fits-together)

---

# Agent Docs

Foundation publishes Markdown-first docs that coding agents can read directly.

Use these when an agent is building, adapting, or reviewing a frontend app that consumes a Foundation backend through `foundation-sdk`.

## Entry Points

- [Foundation app builder](https://docs.foundationmvp.com/agents/foundation-app-builder.md) - workflow for creating, extending, or reviewing consumer apps.
- [Foundation SDK reference](https://docs.foundationmvp.com/agents/foundation-sdk-reference.md) - SDK initialization, auth, services, and web component rules.
- [Foundation deploy contract](https://docs.foundationmvp.com/agents/foundation-deploy-contract.md) - `mvp.config.json`, build output, and `/foundation-env.json`.
- [llms.txt](/llms.txt) - short index for agents.
- [llms-full.txt](/llms-full.txt) - complete concatenated docs bundle.

## How To Use

Tell the agent to start with:

```text
Use https://docs.foundationmvp.com/agents/foundation-app-builder.md to build this app against Foundation.
```

For review work:

```text
Use https://docs.foundationmvp.com/agents/foundation-app-builder.md to review this repo before Foundation deployment.
```

The agent docs are intentionally raw Markdown rather than rendered pages. They are easier for coding agents to fetch, cite, and follow.

---

# Branding

Your app's identity — name, logo, colors, and the details that make it yours. Set it once here, and
Foundation uses it to style your app and hands it to your frontend so everything stays consistent.

## Configure

Branding is the single source of truth for who your app is. Set it in the dashboard, the wizard, or by
telling your agent.

| Field | Used for |
|---|---|
| **App name** | Page titles, emails, the app shell |
| **Logo & icon** | Header, favicon, login screens |
| **Primary color** | Accent color across the built-in UI |
| **Business name, tagline, description** | Marketing surfaces, metadata, emails |
| **Contact emails** | Support links and transactional email (label + address) |
| **Social links** | Footer and profile links (label + URL) |
| **Other links** | Anything else you want surfaced (label + URL) |

Set these once. Foundation styles the built-in UI with them, and your own frontend reads the same
values — so your name and colors live in one place, not scattered through your code.

## Use in your app

Your frontend reads branding from config instead of hard-coding it.

**Tell your agent:** "Use the app's name, logo, and primary color from Foundation config in the header
and the page title."

```ts
const app = foundation.config.app     // name, logo, icon, and the business details you set
const theme = foundation.config.theme // primary color and theme tokens
```

## Reference

- SDK: `foundation.config.app`, `foundation.config.theme` — see the
  [SDK reference](/api/sdk)
- [Billing & Plans](/platform/billing) · [Authentication](/platform/auth)

---

# Frontend

Where your app's interface comes from. Build your own UI and point Foundation at it, or use
Foundation's built-in components — either way, it connects to your backend automatically.

## Configure

### Choose your UI source

| Source | What it is |
|---|---|
| **Foundation-hosted** | Use the built-in UI components (login, registration, settings, plans) — nothing to host. |
| **External URL** | Point to a frontend you host yourself. |
| **GitHub repo** | Connect a repo (public or **private**) and Foundation builds and serves it. |

> This section just sets where your UI lives. Everything else about your app — data, auth, billing —
> is set in the other sections.

## Use in your app

However you host it, your frontend talks to the backend through the Foundation SDK and connector:
bootstrapping, login and registration, websockets, your entities, and your integrations — all wired up.
Bring your own framework, or drop in the built-in web components.

**Tell your agent:** "Set up the Foundation SDK in my app and gate the dashboard behind login."

```ts
import { createFoundation } from 'foundation-sdk'
import { cognitoAuth } from 'foundation-sdk/cognito'

// initialize once, then share it through your app's context/state
const foundation = await createFoundation({ auth: cognitoAuth })
```

Prefer not to build the UI yourself? Use the built-in components — e.g. `<foundation-connect>` for
service connections.

## Reference

- [SDK reference](/api/sdk) — init, auth, data, components
- [Authentication](/platform/auth) · [Deployments](/platform/deployment)

---

# Authentication

Decide whether your app has users — and if so, how they sign in. Turn it on and your app gets login,
registration, accounts, and an API, with no auth code to write.

## Configure

### 1. Do you need users?

| Choice | What happens |
|---|---|
| **No users** | Your app has no login. Good for API services, MCP tool servers, webhook relays. |
| **Users on** | Your app gets login, registration, accounts, sessions, and API keys. |

### 2. Pick a sign-in method

| Method | When |
|---|---|
| **Built-in (Cognito)** | The default. Fully managed — nothing to set up. |
| **Auth0** | Enterprise needs. *(Advanced — coming soon.)* |
| **None** | No login at all. |

### 3. Email verification

Choose whether new users must verify their email, and configure the verification settings.

### Your app is also an OAuth provider

Every app with users is a full OAuth 2.0 provider. Other apps, bots, and services can authenticate
*against* your app — so an API service or chatbot plugin can simply hand out tokens, no UI required.
Users can also generate **API keys** for programmatic access, which respect the same roles and scopes.

## Use in your app

Foundation runs the auth flow; your frontend calls the SDK. Use the built-in login and registration
components, or build your own screens.

**Tell your agent:** "Add sign-in and registration using Foundation auth, and send people to the
dashboard once they're logged in."

```ts
// sign in
const result = await foundation.auth.signIn(email, password)
if (result.isSignedIn) router.push('/dashboard')

// who's logged in
foundation.auth.user
foundation.auth.isAuthenticated

// react to auth changes
foundation.auth.onChange(() => refreshUI())

// sign out
await foundation.auth.logout()
```

On a hosted-login callback route, call `foundation.auth.handleCallback()`.

## Reference

- SDK auth methods: `signIn`, `signUp`, `handleCallback`, `onChange`, `getToken`, … — see the
  [SDK reference](/api/sdk)
- [Authentication API](/api/authentication)
- [Roles & Scopes](/platform/roles) — who can do what

---

# Billing & Plans

Decide whether your app charges money. If it does, Foundation handles the hard parts —
subscriptions, payments, invoices, and enforcing what each plan includes — while you keep your own
Stripe account. You set the plans; your app just reads who's on what.

## Configure

The part you decide — set it in the dashboard, the wizard, or by telling your agent. Four steps:

### 1. Does your app charge?

| Choice | What happens |
|---|---|
| **No payments** | Leave billing off — you're done. Skip the rest of this page. |
| **Stripe** | Turn on payments and connect Stripe. Everything below applies. |

### 2. Connect Stripe

Two ways to connect — your Stripe account stays **yours** either way:

| | What it is | Best when |
|---|---|---|
| **Stripe Connect** | You're sent to Stripe, approve, and you're back. No keys to handle. | You'd rather not deal with keys. |
| **API keys** | Paste a scoped publishable + secret key from your account. | You want explicit control. |

> Foundation sets up a webhook in your Stripe account and keeps your plans and prices in sync — automatically.

### 3. Define your plans

For each plan, set a **name**, **price**, **billing interval**, and **what it unlocks**:

| Plan | Price | Includes |
|---|---|---|
| Free | $0 | 100 API calls/mo · 1 GB storage |
| Pro | $20/mo | 10,000 API calls/mo · 50 GB · AI features |

### 4. Choose how limits are enforced

| Option | Who handles gating |
|---|---|
| **Built-in** | Foundation shows upgrade prompts and enforces limits for you. |
| **Self-managed** | Your app reads the plan + usage and decides what to show ([see below](#use-in-your-app)). |

## Use in your app

You don't have to write any of this — **your agent does**, using the Foundation SDK. Tell it what you
want in plain language; the code is right there too, if you'd rather write it yourself or check the
agent's work.

### Read the plan and usage

**Tell your agent:** "Load the signed-in user's plan and current usage so I can show it on the account page."

```ts
const account = await foundation.account.get()   // current user, including their plan
const usage = await foundation.account.usage()   // metered consumption vs configured limits
const plans = foundation.config.plans            // every plan you defined, from backend config
```

### Gate a feature by plan

**Tell your agent:** "Show an upgrade prompt when someone hits their API limit, and hide AI features for plans that don't include them."

```ts
const usage = await foundation.account.usage()

// Fields on `usage` mirror the capabilities you configured above —
// e.g. an "apiCalls" capability surfaces here as usage.apiCalls.
if (usage.apiCalls.used >= usage.apiCalls.limit) {
  showUpgradePrompt()
}

// Hide what the plan doesn't include — read it from config, don't hard-code tiers:
if (!foundation.config.features.aiFeatures) {
  // this plan doesn't unlock AI — don't render the AI panel
}
```

### Upgrade prompts

**Tell your agent:** "Use Foundation's built-in upgrade prompts" — or "build a custom upgrade screen from the plan and usage data."

- **Built-in gating** — Foundation renders the limit and upgrade UI automatically. Nothing to wire up.
- **Custom** — your agent drives prompts off the plan and usage data above.

Full method signatures: [SDK reference](/api/sdk).

## Reference

- SDK methods used here: `foundation.account.get()`, `foundation.account.usage()`,
  `foundation.config.plans`, `foundation.config.features` — see the
  [SDK reference](/api/sdk)
- [Roles & Scopes](/platform/roles) for per-permission gating
- [MCP & API Overview](/api/overview)

---

# Entities

Entities are your app's data models — the things it tracks. Define one and Foundation gives you a
database table with full create/read/update/delete, queries, and an API. No schema work, no DevOps.

## Configure

### Define an entity

An entity has a name and fields. Set it up in the dashboard, the wizard, or by telling your agent:

> "Add an entity called Projects with fields: name (text), status (text), due date (date)."

Foundation creates the table, generates CRUD, and optionally exposes it over your API or MCP.

### What each entity gives you

- Create, read, update, delete
- Query, filter, and paginate
- Access control via [roles & scopes](/platform/roles)

### Choose how it's exposed

| Surface | Who uses it |
|---|---|
| **REST API** | Your own app |
| **API as a Service** | Your users, programmatically |
| **MCP** | AI agents |

Toggle these per entity.

## Use in your app

Your frontend reads and writes entities through the SDK — typed, with filtering and pagination.

**Tell your agent:** "List the current user's projects, newest first, and let them add a new one."

```ts
// list with filters + pagination
const { items, nextCursor } = await foundation.db.list('projects', {
  orderBy: 'createdAt',
  orderDir: 'desc',
  limit: 50,
})

// create / update / delete
const project = await foundation.db.create('projects', { name, status: 'active' })
await foundation.db.update('projects', project.id, { status: 'done' })
await foundation.db.delete('projects', project.id)
```

## Reference

- SDK data methods: `foundation.db.list / get / create / update / save / delete` — see the
  [SDK reference](/api/sdk)
- [Uploads & Files](/platform/uploads) · [Storage](/platform/storage) · [Roles & Scopes](/platform/roles)
- [REST API](/api/rest) · [MCP Tools](/api/mcp)

---

# Uploads & Files

Let your app's users upload and manage files — images, documents, anything. Foundation stores them
securely, ties each to the user who uploaded it, and respects your access rules.

## Configure

Turn on file uploads and set the rules:

| Setting | What it controls |
|---|---|
| **Allowed types** | Which file types can be uploaded (images, documents, …) |
| **Size limits** | Maximum file size |
| **Access control** | Who can upload, who can view — via [roles & scopes](/platform/roles) |

Files are stored securely and served through your app's API. Each file belongs to the user who
uploaded it.

## Use in your app

Upload straight from the browser with the SDK — Foundation handles the secure, signed upload.

**Tell your agent:** "Let users upload an avatar image and show it on their profile."

```ts
// compute a sha256 of the file, then upload
const result = await foundation.files.upload({
  name: file.name,
  contentType: file.type,
  file,
  sha256,
})

// fetch / list / delete
const meta = await foundation.files.get(result.id)
const { items } = await foundation.files.list({ limit: 50 })
await foundation.files.delete(result.id)
```

For manual control of the signed upload, use `foundation.files.initiate(...)`.

## Reference

- SDK file methods: `foundation.files.upload / initiate / get / list / delete` — see the
  [SDK reference](/api/sdk)
- [Entities](/platform/entities) · [Storage](/platform/storage)

---

# Storage

A built-in key/value store for the small stuff — user preferences, settings, feature flags — without
defining a full entity.

## Configure

Enable the storage collection and use it for simple keyed values: per-user settings, app
configuration, flags. Access is governed by [roles & scopes](/platform/roles) like everything else.

Reach for **Storage** for loose key/value data, and [Entities](/platform/entities) for structured
records you'll query and list.

## Use in your app

Your app reads and writes storage through its data API — values keyed by name, scoped to the user or
the app. See the [SDK reference](/api/sdk) for the current data methods.

## Reference

- [Entities](/platform/entities) — for structured, queryable data
- [Uploads & Files](/platform/uploads) — for binary files
- [SDK reference](/api/sdk)

---

# Chat

Built-in conversation storage for chatbots and AI experiences — messages, threads, and state — so you
don't model chat history from scratch.

## Configure

Enable chat and Foundation gives you a place to store conversations, messages, and per-conversation
state. It's built for AI chat: pair it with [Actions](/platform/ai) to power a bot that remembers
context. Access follows your [roles & scopes](/platform/roles).

## Use in your app

Your chat UI reads and writes conversations and messages through your app's data API, and calls your
[Actions](/platform/ai) to generate responses. See the [SDK reference](/api/sdk).

## Reference

- [Actions](/platform/ai) — the AI that powers responses
- [Entities](/platform/entities) · [SDK reference](/api/sdk)

---

# Actions

Add AI to your app: configurable prompts and chains that can read your data and call your integrations,
exposed as endpoints or MCP tools. In the dashboard these are **Your Actions**.

## Configure

### Prompts

A prompt is a configurable AI action — you set the system prompt, the input schema, and the output
format. Your app, or an agent, invokes it.

### Chains

Chain prompts together for multi-step workflows — each step's output feeds the next.

### Tools

Prompts can use **tools** — real connections to your app:

- **Entity tools** — read and write your [data](/platform/entities) during a run
- **Integration tools** — call [external services](/platform/integrations) during a run

So your AI actions work on real data and real services, not just text.

### Expose & scope

Each action can be enabled, exposed over **REST** or **MCP**, and scoped to specific
[roles](/platform/roles).

> "Create an action called Summarize Project that reads from the Projects entity and returns a status summary."

## Use in your app

Actions run on the backend. Your app invokes them through the surface you exposed them on — your app's
REST API or its MCP server — not a direct SDK call. Turn an action on, expose it, and call it like any
other endpoint.

## Reference

- [Entities](/platform/entities) · [Integrations](/platform/integrations) — what actions can use
- [MCP Tools](/api/mcp) · [REST API](/api/rest) — how actions are exposed and called

---

# API Configuration

Control your app's API surface — whether it's on, who can reach it, and how outside developers use it.
This is where the [runtime API](/understand/managing-vs-running) your app exposes gets turned on and
governed.

## Configure

### Turn on the backend API

Enable your app's REST API and MCP server. Each [entity](/platform/entities), [action](/platform/ai),
and [integration](/platform/integrations) is exposed individually — flip on only what you want reachable.

### Allowed origins (CORS)

Add the domains allowed to call your API from a browser, so your frontend — and only the sites you
choose — can reach it.

### API as a Service

Turn this on to let *your* users access your app programmatically. They get their own API keys and can
build on top of your app.

### Monitoring

Watch usage and traffic across your API.

## Use in your app

Your own frontend calls these endpoints through the [SDK](/api/sdk). For
outside developers, see [API as a Service](/api/api-service). The full endpoint and tool reference lives
in [MCP & API](/api/overview).

## Reference

- [MCP & API Overview](/api/overview) · [REST API](/api/rest) · [MCP Tools](/api/mcp)
- [API as a Service](/api/api-service) · [Authentication API](/api/authentication)
- [Roles & Scopes](/platform/roles) · [Usage Plans](/platform/usage-plans)

---

# Roles & Scopes

One permission system across your whole app — who (and which bots) can read, write, or manage every
entity, integration, action, and endpoint.

## Configure

### Roles

Define roles for your users — each decides what someone can access and do. Examples: Admin / Member /
Viewer, or Photographer / Client, or Free / Premium.

### Scopes

Scopes are the granular permissions a role carries. A scope can control:

- Which [entities](/platform/entities) a role can read, write, or manage
- Which [integrations](/platform/integrations) a role can use
- Which [actions](/platform/ai) it can invoke
- Which API endpoints are reachable

> "Create a viewer role that can read Projects but not edit anything."
> "Create a public scope that only exposes the product catalog."

### Bot-to-bot access

Scopes aren't just for people. When another AI agent connects over MCP, its token carries scopes — so
you control exactly what an external agent can see and do.

## Use in your app

Access is enforced by the backend automatically — calls that exceed a user's scope are rejected, so you
don't re-check permissions in the frontend. Read the current user's role from their account to tailor
the UI.

## Reference

- [Entities](/platform/entities) · [Integrations](/platform/integrations) · [Actions](/platform/ai)
- [Authentication](/platform/auth) · [Authentication API](/api/authentication)

---

# Usage Plans

Define the usage limits your [billing plans](/platform/billing) enforce — how much of each capability a
plan includes, metered and capped for you.

## Configure

A usage plan maps a capability to a limit. Your [billing](/platform/billing) plans reference these, so
"Pro includes 10,000 API calls" is enforced automatically.

| Set | Example |
|---|---|
| **Capability** | API calls, storage, AI actions |
| **Limit** | 10,000 / month, 50 GB |
| **Plan it belongs to** | Free, Pro |

Foundation meters usage per user and enforces the limit — no metering code on your side.

## Use in your app

Read a user's usage and remaining allowance to show meters or gate features — the same data the
[Billing](/platform/billing#use-in-your-app) page uses.

**Tell your agent:** "Show the user's API usage this month as a progress bar."

```ts
const usage = await foundation.account.usage()  // consumption vs configured limits
```

## Reference

- [Billing & Plans](/platform/billing) — the plans these limits attach to
- [API Configuration](/platform/api-configuration) · [SDK reference](/api/sdk)

---

# Integrations

Connect your app to external services — anything that uses OAuth, API keys, or bearer tokens. Foundation runs the auth flow and stores the tokens; your app just manages connections and calls the capabilities you expose.

This page has two halves: **Configure** sets integrations up on the platform (no code), and **Use in your app** wires connection management into the frontend you're building.

## Configure

Set integrations up on the platform side — in the dashboard or by asking your agent. No code required.

### Connect a service

Add an integration and Foundation handles the auth flow end to end: OAuth redirects, token storage, and refresh tokens. You don't see or store secrets in your app.

### Map capabilities

Each integration exposes capabilities — the methods you can call on the external service. A Google Calendar integration might expose:

- List events
- Create event
- Update event
- Delete event

### Choose how capabilities are exposed

- **REST API** — your app's users call integration methods through your API
- **MCP** — AI agents use your integrations as tools
- **AI Prompts** — wire integrations into your prompt chains as tools

### Control access

Integration access is governed by [roles and scopes](/platform/roles). You decide which users and which external agents can use which integrations.

## Use in your app

The SDK manages **connections** — listing the catalog, connecting, checking status, disconnecting. Invoking an integration's capabilities (list events, etc.) happens through the surface you exposed in Configure (your REST API or MCP), not a direct SDK call. Full method signatures live in the [SDK reference](/api/sdk).

### Show the catalog and connection state

```ts
const integrations = await foundation.integration.all()  // catalog + current connection state
```

Use `all()` rather than stitching `list()` and `connections()` yourself.

### Connect a service

```ts
const result = await foundation.integration.connect(source)

if (result.url) {
  // open a popup or redirect, then refresh connection status when it returns
  window.open(result.url, 'connect', 'width=600,height=700')
}
// also handle immediate success / configuration responses
```

### Disconnect

```ts
// only after explicit user confirmation
await foundation.integration.disconnect(source, configurationId)
```

### Drop-in connect button (optional)

If you don't want to build the connect UI, use the web component:

```ts
import 'foundation-sdk/components'
;(window as any).__foundation = foundation
```

```html
<foundation-connect integration-id="github-oauth"></foundation-connect>
```

It emits `success`, `error`, and `close` events. In Vue, configure `isCustomElement` for `foundation-*` tags.

## Reference

- SDK methods used here: `foundation.integration.all()`, `.connect()`, `.disconnect()`, `.status()`, `.connections()` — see the [SDK reference](/api/sdk)
- [Roles & Scopes](/platform/roles) for per-integration access control
- [MCP & API Overview](/api/overview) for exposing capabilities as tools

---

# Deployments

When you're ready, publish your changes so your app goes live with them. Choose where it runs based on
how far along you are.

## Configure

### Publish your changes

Configuration changes — new entities, plans, settings — take effect when you **deploy**. Until then
you're editing a draft; deploy to push it live.

### Shared or dedicated

| | What it is | Best for |
|---|---|---|
| **Shared** | Runs on Foundation's shared infrastructure | Getting started, side projects, early stage |
| **Dedicated** | Your own isolated compute, database, and storage | Production, businesses, higher capacity |

Dedicated adds your own [custom domain and SSL](/platform/domains) and full OAuth-provider
capabilities — e.g. "Login with Google" for *your* users.

### Moving between tiers

Start shared, go dedicated when you're ready — Foundation handles the migration.

## Use in your app

Deployment isn't something your frontend calls — it's how your app gets shipped. What your app's
**repository** needs in order to deploy (required files and environment values) is the deploy
contract:

→ [Deploy contract](/agents/foundation-deploy-contract.md)

## Reference

- [Deploy contract](/agents/foundation-deploy-contract.md) — required files and env for your app repo
- [Domains & SSL](/platform/domains)

---

# Domains & SSL

Use your own domain with your Foundation app. SSL certificates are managed automatically.

## Custom Domains

Point your domain to your Foundation app. Available on dedicated deployments.

## SSL

SSL certificates are provisioned and renewed automatically. Your app is always served over HTTPS.

---

# Building on Foundation

You've configured the backend. Building is turning it into an app people use — a frontend (or another
app, or an agent) that consumes what Foundation already set up: the endpoints, the auth, the data, the
components. You write what's unique; the backend is already there.

## What you build with

- **A live backend** — your entities, auth, billing, integrations, and an API, already running.
- **The SDK** (`foundation-sdk`) — one typed client for auth, data, files, integrations, account, and
  config. [Set it up](/build/sdk).
- **Built-in UI components** — login, registration, settings, plans — drop in or replace.
- **A deploy contract** — one config file and Foundation builds and hosts your app. [Deploy](/build/deploy).

## You don't have to build it by hand

Most people don't write this themselves — their agent does. Point your agent at the
[Agent toolkit](/build/agent-toolkit) and describe what you want; it uses the SDK to assemble the app.
The pages here are written so your agent has everything it needs.

## The path

1. [Set up the SDK](/build/sdk) — one initialization, shared across your app.
2. [Use your backend](/build/using-your-backend) — auth, data, files, billing from the SDK.
3. [Add the UI](/build/components) — built-in components or your own.
4. [Deploy](/build/deploy) — add one config file, ship.

Or hand the whole thing to an agent with the [Agent toolkit](/build/agent-toolkit).

---

# Set up the SDK

Your app talks to its Foundation backend through `foundation-sdk` — one typed client you initialize
once and share everywhere.

## Install

```bash
npm install foundation-sdk
# plus your auth provider:
npm install aws-amplify              # Cognito (default)
# or: npm install @auth0/auth0-spa-js   # Auth0
```

## Initialize once

Await `createFoundation(...)` a single time and share the instance through your app's context or state.

```ts
import { createFoundation } from 'foundation-sdk'
import { cognitoAuth } from 'foundation-sdk/cognito'

export const foundation = await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL, // dev-only, optional
  auth: cognitoAuth,
})
```

For Auth0, import `auth0Auth` from `foundation-sdk/auth0` instead.

## Dev vs production

| | How identity is provided |
|---|---|
| **Local dev** | Pass `configUrl`, `tenantId`, `appId` (and optional dev-only `baseUrl`) explicitly. |
| **Production** | Foundation writes `/foundation-env.json` at deploy and the SDK reads it automatically — so `createFoundation({ auth })` works with no identity values. |

## Rules that matter

- Always `await createFoundation(...)`.
- Initialize **once** — never a second `createFoundation()` call.
- Use exactly one auth provider entry point.
- `baseUrl` is **dev-only**; production must not depend on it.
- Never put private secrets in frontend code.

## Reference

- [SDK reference](/api/sdk) — every method
- [Deploy your app](/build/deploy) — how `/foundation-env.json` gets written

---

# Using your backend

Once the [SDK is set up](/build/sdk), every capability you configured is available through the
`foundation` instance. Each Configure page has a **Use in your app** section with the exact calls —
here's the map.

| Capability | In your app | SDK |
|---|---|---|
| [Authentication](/platform/auth#use-in-your-app) | Login, registration, sessions | `foundation.auth.*` |
| [Entities](/platform/entities#use-in-your-app) | Read and write your data | `foundation.db.*` |
| [Uploads & Files](/platform/uploads#use-in-your-app) | File uploads | `foundation.files.*` |
| [Billing](/platform/billing#use-in-your-app) | Plans, usage, gating | `foundation.account.*`, `foundation.config.plans` |
| [Integrations](/platform/integrations#use-in-your-app) | Connect services | `foundation.integration.*` |
| [Branding](/platform/apps#use-in-your-app) | App name, theme | `foundation.config.*` |

## Patterns that apply everywhere

- Handle **unauthenticated** users before calling authenticated services.
- Add **loading, empty, success, and error** states to every call.
- **Paginate** lists that can grow (`limit` + `cursor`).
- Read `foundation.config` for backend-provided theme, features, and plans instead of hard-coding them.

## Reference

- [SDK reference](/api/sdk)

---

# Components & connector

Build your UI from scratch against the [SDK](/build/sdk), or use Foundation's built-in web components
for the common screens.

## Built-in components

Import the component bundle and expose your initialized instance:

```ts
import 'foundation-sdk/components'
;(window as any).__foundation = foundation
```

Then drop components into your markup — for example, a service-connect button:

```html
<foundation-connect integration-id="github-oauth"></foundation-connect>
```

Components emit `success`, `error`, and `close` events. In Vue, configure `isCustomElement` for
`foundation-*` tags.

## The connector

However you host your frontend ([Frontend](/platform/frontend)), the connector handles bootstrapping,
auth, websockets, and access to your entities and integrations — so your UI is wired to the backend
without glue code.

## Bring your own UI

Prefer full control? Skip the components and call the [SDK](/build/sdk) directly. Login, data, billing,
and integrations all work the same way.

## Reference

- [SDK reference](/api/sdk) · [Frontend](/platform/frontend)

---

# Deploy your app

Foundation builds and hosts your frontend from your Git repo. You add one config file; Foundation does
the rest.

## The one file you add: `mvp.config.json`

At your app repo root:

```json
{
  "build": "npm install && npm run build",
  "files": "dist",
  "entry": "index.html",
  "sdk": "^1.0.0"
}
```

| Field | Meaning |
|---|---|
| `build` | Command Foundation runs before deploying |
| `files` | Build output directory to upload |
| `entry` | Entry file inside `files` |
| `sdk` | SDK compatibility hint |
| `node` | Optional Node major version |

Adjust `files` and `entry` only if your framework builds somewhere other than `dist` / `index.html`.

## What happens on deploy

Foundation reads `mvp.config.json` from GitHub, downloads the repo, runs your build, uploads the output
directory, and writes `/foundation-env.json` next to the built assets. The SDK reads that file
automatically in production — so production code needs no identity values and no `baseUrl`.

> Don't create `/foundation-env.json` yourself for production — Foundation writes it.

## Before you ship — checklist

- `mvp.config.json` exists at the repo root with `build`, `files`, and `entry`.
- The build command succeeds and produces the `files` directory containing the `entry` file.
- The SDK initializes from explicit config locally, and from `/foundation-env.json` in production.
- Production doesn't depend on `baseUrl`.
- Built assets contain no private secrets.

## Reference

- [Deploy contract](/agents/foundation-deploy-contract.md) — canonical
- [Deployments](/platform/deployment) — shared vs dedicated
- [Set up the SDK](/build/sdk)

---

# Agent toolkit

Most Foundation apps are built by an agent, not by hand. This is what you point your agent at — the
workflow, references, and starter prompt that let it build your app correctly.

## Point your agent at the docs

Every page here has a clean Markdown version (add `.md` to any URL), plus a bundle for ingest:

| Resource | URL |
|---|---|
| **App builder workflow** | https://docs.foundationmvp.com/agents/foundation-app-builder.md |
| **SDK reference** | https://docs.foundationmvp.com/agents/foundation-sdk-reference.md |
| **Deploy contract** | https://docs.foundationmvp.com/agents/foundation-deploy-contract.md |
| **Everything (one file)** | https://docs.foundationmvp.com/llms-full.txt |

## Starter prompt

Paste this into your agent and fill in the blanks:

```text
Use https://docs.foundationmvp.com/agents/foundation-app-builder.md to build a production-ready
frontend app that consumes the Foundation backend.

App goal:
Framework and router:
Styling system:
Auth provider: Cognito or Auth0
Foundation config URL for local development:
Foundation tenant ID for local development:
Foundation app ID for local development:
Optional local API proxy base URL:
Entities to use through foundation.db:
File workflows to support through foundation.files:
Integrations to support through foundation.integration:
Account/profile fields:
Deployment output directory:
Deployment entry file:
```

## What the agent will do

Given those docs, your agent installs `foundation-sdk`, sets up one SDK initialization, builds login /
registration / guarded routes, implements your data and file workflows, adds `mvp.config.json`, and
checks the app is deploy-ready — following the
[app builder workflow](/agents/foundation-app-builder.md).

## Reference

- [Set up the SDK](/build/sdk) · [Deploy your app](/build/deploy)
- [Agent Docs](/guide/agent-docs) — how these agent docs are served

---

# MCP & API Overview

Every Foundation app can expose its capabilities over REST API and MCP (Model Context Protocol). This means your data, actions, and integrations are accessible to other apps, services, and AI agents.

## REST API

Standard REST endpoints for your app's entities, actions, and integrations. Authenticated via OAuth tokens or API keys.

## MCP Server

Your app is also an MCP server. Any MCP-compatible client (Claude Desktop, AI agents, other tools) can connect and interact with your app's capabilities.

## API as a Service

Expose your API to your app's end users. They get their own API keys and can build on top of your app programmatically.

## What Gets Exposed

You control what's accessible. Per entity, per action, per integration — toggle REST and MCP exposure independently. Combine with roles and scopes for fine-grained access control.

---

# SDK Reference

`foundation-sdk` is the typed client your frontend uses to talk to its Foundation backend — auth, data,
files, integrations, account, and config, from one instance you [set up once](/build/sdk).

> The canonical, agent-oriented version of this reference is served at
> [`/agents/foundation-sdk-reference.md`](/agents/foundation-sdk-reference.md) and bundled into
> `llms-full.txt`. This page is the same surface, rendered for reading.

## Install

```bash
npm install foundation-sdk
npm install aws-amplify            # Cognito apps
# or: npm install @auth0/auth0-spa-js   # Auth0 apps
```

## Initialize

Await once, share everywhere. See [Set up the SDK](/build/sdk) for dev vs production details.

```ts
import { createFoundation } from 'foundation-sdk'
import { cognitoAuth } from 'foundation-sdk/cognito' // or auth0Auth from 'foundation-sdk/auth0'

const foundation = await createFoundation({
  configUrl: import.meta.env.VITE_FOUNDATION_CONFIG_URL,
  tenantId: import.meta.env.VITE_FOUNDATION_TENANT_ID,
  appId: import.meta.env.VITE_FOUNDATION_APP_ID,
  baseUrl: import.meta.env.VITE_FOUNDATION_API_BASE_URL, // dev-only
  auth: cognitoAuth,
})
```

In production, Foundation writes `/foundation-env.json` and the SDK reads it — so `createFoundation({ auth })` works with no identity values.

## Auth

```ts
foundation.auth.user
foundation.auth.isAuthenticated
foundation.auth.getToken()
foundation.auth.login(options?)
foundation.auth.logout(options?)
foundation.auth.handleCallback(url?)
foundation.auth.signIn(email, password)
foundation.auth.signUp(email, password, metadata?)
foundation.auth.confirmSignUp(email, code)
foundation.auth.resendSignUpCode(email)
foundation.auth.forgotPassword(email)
foundation.auth.resetPassword(code, newPassword)
foundation.auth.onChange(callback)
```

Sign-in and sign-up return result objects — branch on `result.isSignedIn` /
`result.nextStep?.signInStep`. Call `handleCallback()` on hosted-login callback routes, and refresh
auth state after login, logout, callback, and registration. See [Authentication](/platform/auth).

## Database

```ts
foundation.db.list<T>(entity, options?)
foundation.db.get<T>(entity, id)
foundation.db.create<T>(entity, data)
foundation.db.update<T>(entity, id, updates)
foundation.db.save<T>(entity, data)
foundation.db.delete(entity, id)
```

`list` options: `{ filters?, limit?, cursor?, orderBy?, orderDir? }`. Paginate with `cursor` /
`nextCursor` for lists that can grow. See [Entities](/platform/entities).

## Files

```ts
foundation.files.upload({ name, contentType, file, sha256 })
foundation.files.initiate({ name, contentType, contentLength, sha256, metadata? })
foundation.files.get(fileId)
foundation.files.delete(fileId)
foundation.files.list({ limit?, cursor? }?)
```

Compute `sha256` before upload. Use `initiate` only for manual control of the signed upload. See
[Uploads & Files](/platform/uploads).

## Integrations

```ts
foundation.integration.all()
foundation.integration.list()
foundation.integration.connections()
foundation.integration.status(source)
foundation.integration.connect(source)
foundation.integration.disconnect(source, configurationId)
```

Use `all()` for catalog plus connection state. On `connect(source)`, if the result has a `url`, open a
popup or redirect, then refresh status. Only `disconnect` after explicit confirmation. See
[Integrations](/platform/integrations).

## Account

```ts
foundation.account.get<TUser, TAccount>()
foundation.account.update(data)
foundation.account.usage()
foundation.account.resendVerification()
```

`usage()` returns consumption vs configured limits — drives plan gating. See [Billing](/platform/billing).

## Config

```ts
foundation.config.app
foundation.config.features
foundation.config.plans
foundation.config.theme
foundation.config.connectors
foundation.config.resources
foundation.config.auth
foundation.config.raw
```

Read backend config to hide unavailable UI and apply theme- or plan-aware behavior instead of
hard-coding. See [Branding](/platform/apps).

## OAuth consent

For apps acting as OAuth authorization servers:

```ts
const client = await foundation.oauth.getClient(clientId)
const { code } = await foundation.oauth.authorizeConsent({
  client_id, redirect_uri, scope, state, code_challenge, code_challenge_method,
})
```

Only call `authorizeConsent` after explicit user approval, then redirect back with `code` and `state`.

## Logging

```ts
foundation.log.info(message, context?)
foundation.log.warn(message, context?)
foundation.log.error(message, context?)
foundation.log.event(eventName, data?)
```

Fire-and-forget — never block the UI on logging.

## Web components

```ts
import 'foundation-sdk/components'
;(window as any).__foundation = foundation
```

```html
<foundation-connect integration-id="github-oauth"></foundation-connect>
```

Events: `success`, `error`, `close`. In Vue, configure `isCustomElement` for `foundation-*` tags. See
[Components & connector](/build/components).

## Critical rules

- Always `await createFoundation(...)`; initialize **once** and share it.
- Use exactly one auth provider entry point.
- `baseUrl` is dev-only — production must not depend on it.
- Never put private secrets in frontend code.
- Set `window.__foundation` only when using `foundation-sdk/components`.

---

# MCP Tools

Your Foundation app exposes MCP tools that any compatible client can use. This is how AI agents interact with your app.

## Available Tools

The tools available on your MCP server depend on what you've configured:

- **Entity tools** — CRUD operations on your data models
- **Action tools** — invoke your AI prompts and chains
- **Integration tools** — call methods on your connected services
- **Management tools** — configure and manage your app (if authorized)

## Connecting

Add your app's MCP endpoint to any MCP client:

1. Get your MCP connection URL from your account
2. Add it to your MCP client's configuration
3. Authenticate with your token
4. Start using tools

## Scoped Access

MCP connections are scoped. The tools available depend on the token's permissions. A public token might only expose read-only entity access. An admin token exposes everything.

---

# REST API

Standard REST endpoints for interacting with your Foundation app programmatically.

## Authentication

All API requests require authentication via:

- **OAuth 2.0 tokens** — for user-context requests
- **API keys** — for service-to-service or programmatic access

## Endpoints

Endpoints are generated based on your app's configuration. Each enabled entity, action, and integration capability gets REST endpoints.

## API as a Service

When enabled, your app's users can access the API with their own API keys. This lets them build integrations and automations on top of your app.

---

# API as a Service

Let your app's users access your API programmatically. They generate their own API keys and interact with the entities, actions, and integrations you've exposed.

## How It Works

1. Enable API as a Service for your app
2. Choose which entities, actions, and integrations to expose
3. Your users generate API keys from their account
4. They make authenticated requests against your app's API

## Use Cases

- Your users build custom integrations with your app
- Third-party developers build on your platform
- Automated workflows that interact with your app's data

---

# API Authentication

All API and MCP access is authenticated. Foundation supports multiple authentication methods.

## OAuth 2.0

Your Foundation app is a full OAuth 2.0 provider. Clients can authenticate using standard OAuth flows.

## API Keys

Users and services can generate API keys for programmatic access. Keys are scoped to the permissions of the user who created them.

## Bearer Tokens

For service-to-service communication, use bearer tokens with specific scopes.

## Scoped Access

All authentication methods respect the roles and scopes you've configured. A token only grants access to what its associated role allows.

---

# Webhooks

Send and receive webhooks to integrate your Foundation app with external services.

## Inbound Webhooks

Receive data from external services. Foundation provides webhook endpoints that trigger automations in your app.

## Outbound Webhooks

Notify external services when events happen in your app. Configure which events trigger webhooks and where they're sent.

---

# Error Handling

Foundation APIs use standard HTTP status codes and return structured error responses.

## Error Format

```json
{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "The requested entity does not exist.",
    "status": 404
  }
}
```

## Common Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad request — check your input |
| 401 | Unauthorized — invalid or missing authentication |
| 403 | Forbidden — valid auth but insufficient permissions |
| 404 | Not found |
| 429 | Rate limited — slow down |
| 500 | Server error |

---

# Building a SaaS Product

Foundation MVP is built for this. Get auth, billing, data, and APIs without writing infrastructure code.

## What You Get

- User accounts with login and registration
- Stripe billing with subscription plans
- Database for your app's data
- API for your frontend or integrations
- Role-based access control
- Usage tracking and plan enforcement

## Example: Project Management Tool

1. Enable users and auth
2. Define entities: Projects, Tasks, Comments
3. Set up billing: Free (5 projects), Pro (unlimited, $20/month)
4. Map usage limits to plans
5. Connect your frontend via the connector SDK
6. Deploy

You have a live SaaS with auth, billing, and data — ready for users.

---

# Building AI-Powered Apps

Foundation makes it easy to add AI capabilities to your app — and to build entire products around AI.

## What You Get

- Configurable prompts and prompt chains
- Tools wired to your data and integrations
- Expose AI actions over REST API and MCP
- Usage-based billing for AI features

## Example: AI Writing Assistant

1. Define prompt actions: "Generate blog post," "Summarize text," "Edit for tone"
2. Wire prompts to a Knowledge Base entity for context
3. Enable billing with usage limits on AI calls
4. Expose actions over API
5. Deploy

Your users get an AI writing tool with real capabilities, usage tracking, and billing.

## Example: Customer Support Bot

1. Define a Chat entity for conversations
2. Create a prompt chain: understand question → search knowledge base → generate response
3. Wire tools to your FAQ entity and ticket system
4. Expose over MCP so agents can use it
5. Deploy

---

# Building a Membership Platform

Create a paid membership with tiers, gated content, and user management.

## What You Get

- User accounts with roles (free member, premium member, admin)
- Billing with multiple tiers
- Content gating based on plan
- File storage for member content
- Member management

## Example: Online Course Platform

1. Enable users with roles: Student, Instructor, Admin
2. Define entities: Courses, Lessons, Progress
3. Set up billing: Free (1 course), Premium ($15/month, all courses)
4. Gate lesson access based on plan
5. Enable file storage for course materials
6. Deploy

---

# Building a Client Portal

Give your clients a branded portal with secure access to their data, files, and project status.

## What You Get

- User accounts with role-based access
- Entities for projects, documents, deliverables
- File storage for shared documents
- Scoped access — each client sees only their data
- Custom branding

## Example: Consulting Firm Portal

1. Enable users with roles: Client, Consultant, Admin
2. Define entities: Projects, Deliverables, Invoices
3. Set up scopes so clients only see their own projects
4. Enable file storage for document sharing
5. Add branding (logo, colors, domain)
6. Deploy

---

# Building an API Product

Sell access to your data or services through a managed API with authentication, rate limiting, and usage-based billing.

## What You Get

- API endpoints generated from your entities and actions
- API key management for your customers
- Usage tracking and rate limiting
- Billing tied to API usage
- Documentation (auto-generated)

## Example: Data API

1. Define entities for your data (Products, Locations, Prices)
2. Enable API as a Service
3. Set up billing: Free (100 calls/day), Pro (10,000 calls/day, $49/month)
4. Map API call limits to plans
5. Deploy

Your customers sign up, get API keys, and start querying your data. You track usage and bill accordingly.

---

# Personal MCP Server

Deploy your own MCP server. Connect your services, add your own data, and let your AI agent (and your friends' agents) interact with your stuff.

## What You Get

- Your own MCP endpoint
- Connect integrations (Google Calendar, GitHub, Spotify, etc.)
- Define custom data (reading lists, recipes, projects, anything)
- Scoped access — control who sees what
- Activity tracking — see who's querying your server

## How It Works

1. Create an app
2. Connect your services and define your data
3. Get your MCP endpoint
4. Add it to Claude Desktop
5. Your AI agent now knows your stuff

## Sharing

Control access with scopes:

- **Private** — only your agent can access
- **Friends** — invite specific people, their agents get scoped access
- **Public** — anyone's agent can query (read-only, specific data)

```
"Let Sarah's agent see my calendar availability."
"Make my recipe collection public."
"Show me who's been accessing my server."
```

## From Personal to Platform

Start with a personal MCP server. As it grows, go dedicated — get your own domain, set up OAuth, let others authenticate into your server. Your personal project becomes a platform.

---