Configuration reference

Use this reference when you need to look up a setting or change an installed app. For your first installation, start with Configuration, which walks through the choices to make before Kickstart.

Three places to configure behavior

Root .env holds installation inputs and generated runtime values. config/ holds source-controlled product choices. Provider-owned resources hold state such as the initialized Stripe catalog. Choose the existing source of truth rather than creating another editable copy.

Keep one assignment per environment name. Kickstart reads root .env; do not add conflicting .env.local values. A local file change does not automatically update deployed variables or hosted Auth/function settings. The action column below explains the next step.

Source configuration

Start with the file responsible for the behavior you want to change. For example, editing a page's marketing copy belongs in source; changing an API key belongs in the private environment; changing an initialized subscription price follows the Stripe catalog workflow.

Change the product name and description

Set your product name in the existing root .env entry:

APP_NAME=Fieldnotes

The complete config/site.ts module can then keep that environment override and supply your product description:

export const site = {
  name: process.env.APP_NAME || 'Fieldnotes',
  description: 'Shared project notes for teams that work with customers.',
}

Restart the development server after changing the environment and verify the header and public metadata. Update the page copy in config/marketing.ts, logos, social artwork and email wording as part of branding. APP_NAME is not a global search-and-replace tool and does not rename provider resources that already exist.

Choose the integration surface

config/integrations.json owns the supported REST/MCP switches. This complete example keeps the REST API available and disables MCP and its OAuth connection flow:

{
  "apiEnabled": true,
  "mcpEnabled": false,
  "oauthEnabled": false,
  "operations": ["get_workspace", "rename_workspace"]
}

Use the existing operation names; adding a string does not implement a new endpoint or permission. Check the server routes and connection UI after the change, and review issued credentials before retiring an integration. REST API and MCP explain the shared contracts.

Common configuration tasks

The sections below list the exact environment fields, including generated values you should preserve. They are a reference for your installed project; you only need the three credentials from Accounts for the first installation.

Application and Supabase values

SUPABASE_ORGANIZATION_SLUG and SUPABASE_REGION are optional bootstrap overrides accepted by the parser even though the example file only links to them in comments. Organization selection uses the real slug. A region override must be available. Neither is another credential.

Email values

These IDs identify published templates; they are not interchangeable with API keys. Source HTML and installer variable definitions must stay aligned. See email delivery.

Billing and AI values

Prices and seat/usage limits are not extra environment variables. Initial prices come from config/billing-seed.json; after initialization, the owned Stripe test catalog becomes the authoring source. This table deliberately does not reproduce an editable catalog. Workspace AI credits are one-time and independent of subscription prices.

GitHub and Vercel values

Google OAuth client ID and secret are configured only in hosted Supabase. Do not add them to this table's runtime environment. The production allowlist is productionEnvironment() in scripts/kickstart/deploy-config.mjs; it is the authoritative code for values that leave the setup computer.

Apply a feature switch

To enable AI on an installed, authorized target, set AI_ENABLED=true, fill OPENROUTER_API_KEY, retain a supported AI_MODEL, and use the scoped AI install procedure. Restart Next.js and verify a real response separately. Changing the visible menu is not equivalent to installing the schema.

For integration switches, disable the corresponding server route and consent surface as defined by the shared config, not only a sidebar item. Database grants and issued credentials still deserve a review when removing a capability. Billing removal similarly requires handling existing subscriptions rather than hiding the Billing tab.

Active and saved URLs

APP_URL drives active application behavior. The two saved references do not create independent local/live Supabase environments. Once deployed, shared Auth/email/MCP settings use production and ordinary local setup stops to prevent accidental reversal. Read origin recovery before changing them.

Validate a configuration change

Identify its consumer, update one source of truth, run the relevant read-only check, then perform only the authorized provisioning/runtime action. Verify the actual UI and failure state. Keep generated identifiers and private receipts. A successful parser or TypeScript check proves neither permissions to write provider resources nor the availability of a configured model or sender.