{"project":{"id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","user_id":"user_cdadee0e9bd5","name":"Emergent","slug":"emergent","description":"","logo_url":null,"primary_color":"#6366f1","created_at":"2026-01-17T09:54:19.136279+00:00","updated_at":"2026-01-17T09:54:19.136281+00:00","is_public":true},"config":{"id":"f9ecba94-8d12-4be9-ad53-2beb2e06259c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","site_title":"Emergent","site_description":"Guides, references and how-tos for building, deploying and shipping apps with Emergent.","favicon_url":"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/brand/favicon.png","theme":"light","layout":"sidebar","primary_color":"#0AADC2","light_color":"#ffffff","dark_color":"#0AADC2","logo_light_url":"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/brand/logo_light.webp","logo_dark_url":"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/brand/logo_dark.webp","logo_link":"https://www.emergent.sh","background_image_url":null,"top_nav_enabled":true,"search_enabled":true,"updated_at":"2026-10-09T06:13:08.716011+00:00","background_pattern":"dots","navbar":{"links":[{"label":"Support","href":"mailto:support@emergent.sh"}],"primary":{"label":"Try Emergent","href":"https://www.emergent.sh"}},"toc_enabled":true,"navigation":{"tabs":[{"id":"learn-the-basics","label":"Learn the Basics","icon":"compass","groups":[{"group":"Getting started","pages":[{"page":"start-with-your-idea","title":"Start with your idea","icon":"lightbulb"},{"page":"talk-it-through","title":"Talk it through first","icon":"message"},{"page":"watch-your-app-come-alive","title":"Watch your app come alive","icon":"eye"},{"page":"make-it-yours","title":"Make it yours","icon":"palette"},{"page":"add-login-user-accounts","title":"Add login & user accounts","icon":"log-in"},{"page":"connect-your-tools","title":"Connect your tools","icon":"plug"},{"page":"try-it-before-you-share-it","title":"Try it before you share it","icon":"check-circle"}],"groups":[]},{"group":"Go live & grow","pages":[{"page":"put-your-app-live","title":"Put your app live","icon":"rocket"},{"page":"share-it-with-the-world","title":"Share it with the world","icon":"send"},{"page":"use-your-own-web-address","title":"Use your own web address","icon":"globe"},{"page":"get-found-on-google","title":"Get found on Google","icon":"search"},{"page":"get-paid","title":"Get paid","icon":"credit-card"},{"page":"get-your-first-users","title":"Get your first users","icon":"users"}],"groups":[]},{"group":"Essentials","pages":[{"page":"how-credits-work-basics","title":"How credits work","icon":"coins"},{"page":"write-prompts-that-work","title":"Write prompts that work","icon":"pencil"},{"page":"checkpoints-undo-anything","title":"Checkpoints: undo anything","icon":"history"},{"page":"when-something-breaks","title":"When something breaks","icon":"wrench"},{"page":"keep-it-safe","title":"Keep it safe","icon":"shield"}],"groups":[],"no_next_up":true}]},{"id":"build","label":"Build","icon":"blocks","groups":[{"group":"Introduction","pages":[{"page":"what-is-emergent","title":"What is Emergent?","icon":"book"},{"page":"what-kind-of-apps-you-can-build","title":"What kind of apps you can build?","icon":"lightbulb"},{"page":"the-chat-to-deployment-flow","title":"The chat-to-publish flow","icon":"rocket"},{"page":"how-apps-work-here-mental-model","title":"How apps work here","icon":"brain"},{"page":"a-tour-of-the-workspace","title":"A tour of the workspace","icon":"layout"}],"groups":[]},{"group":"Getting Started","pages":[{"page":"what-is-a-job","title":"What is a Job?","icon":"folder"},{"page":"team-roles-permissions-collaboration","title":"Team roles, permissions & collaboration","icon":"users"},{"page":"understanding-models-e1-e2-e3-maxx","title":"Understanding models (E1/E2/E3 & Maxx)","icon":"brain"},{"page":"previewing-iterating","title":"Previewing & iterating","icon":"eye"},{"page":"debugging-testing-with-the-agent","title":"Debugging & testing with the agent","icon":"bug"},{"page":"building-from-the-emergent-mobile-app","title":"Building from your phone","icon":"layers"}],"groups":[]},{"group":"Useful Tools while building","pages":[{"page":"forking","title":"Forking","icon":"git-branch"},{"page":"the-universal-llm-key","title":"The Universal LLM Key","icon":"key"}],"groups":[]},{"group":"Publishings","pages":[],"groups":[{"group":"Common","pages":[{"page":"pre-deploy-pre-publish-health-check","title":"Pre-publish health check for web apps","icon":"shield-check"},{"page":"secrets-env-variables","title":"Secrets & env variables","icon":"lock"},{"page":"deployment-types","title":"Publishing types","icon":"rocket"},{"page":"database-mongodb","title":"Database (MongoDB)","icon":"database"},{"page":"deployment-plan-levels","title":"Publishing plan levels","icon":"rocket"},{"page":"enable-seo-crawler-pre-rendering","title":"Enable SEO: crawler pre-rendering","icon":"search"}]},{"group":"Web flow","pages":[{"page":"deploying-web","title":"Publishing your web app","icon":"rocket"},{"page":"preview-vs-deployed-separate","title":"Preview vs Published","icon":"eye"},{"page":"custom-domain","title":"Custom domain","icon":"globe"},{"page":"web-mobile-conversion-canonical","title":"Web to Mobile conversion","icon":"layers"}]}]},{"group":"Credits, Plans & Billing","pages":[{"page":"plans-the-free-tier","title":"Plans & the free tier","icon":"file-text"},{"page":"managing-credit-usage","title":"Managing credit usage","icon":"gauge"},{"page":"referrals-partners-program","title":"Referrals & Affiliates program","icon":"users"},{"page":"payment-methods-regional-billing","title":"Payment methods & regional billing","icon":"tag"},{"page":"cancellation-refunds","title":"Cancellation & refunds","icon":"tag"},{"page":"enterprise-plan-features","title":"Enterprise plan & features","icon":"building"}],"groups":[]},{"group":"Agents","pages":[{"page":"custom-agents","title":"Custom agents","icon":"robot"},{"page":"how-the-agent-runs-workflow-stop-reasons","title":"How the agent runs (workflow & stop reasons)","icon":"robot"}],"groups":[]}]},{"id":"mobile-apps","label":"Mobile Apps","icon":"rocket","groups":[{"group":"Mobile Apps","pages":[{"page":"starting-the-process","title":"Starting the process","icon":"rocket"},{"page":"pre-publish-health-check","title":"Pre-publish health check","icon":"shield-check"},{"page":"database-data-on-mobile","title":"Database & data on mobile","icon":"database"},{"page":"package-name-bundle-id-app-id","title":"Package name, Bundle ID & App ID","icon":"package"},{"page":"publishing-to-the-stores","title":"Publishing to the stores","icon":"rocket"},{"page":"monetisation-in-app-purchases-subscriptions","title":"Monetisation: in-app purchases & subscriptions","icon":"tag"},{"page":"push-notifications","title":"Push notifications","icon":"file-text"},{"page":"build-generation-for-a-pre-existing-play-store-app","title":"Build generation for a pre-existing Play Store app","icon":"file-text"},{"page":"troubleshooting","title":"Troubleshooting","icon":"file-text"},{"page":"best-practices","title":"Best Practices","icon":"list-checks"},{"page":"web-mobile-conversion-canonical","title":"Web to Mobile conversion","icon":"layers"}],"groups":[]}]},{"id":"integrations","label":"Integrations","icon":"puzzle","groups":[{"group":"Overview","pages":[{"page":"what-and-how","title":"What and How","icon":"file-text"},{"page":"mcps-connectors","title":"MCPs & connectors","icon":"puzzle"},{"page":"key-integrations-catalogue","title":"Key integrations catalogue","icon":"puzzle"}],"groups":[]},{"group":"Payments","pages":[{"page":"stripe","title":"Stripe","icon":"tag"},{"page":"razorpay","title":"Razorpay","icon":"tag"},{"page":"paystack","title":"Paystack","icon":"tag"},{"page":"paypal","title":"PayPal","icon":"tag"}],"groups":[]},{"group":"Data & auth","pages":[{"page":"emergent-auth-built-in","title":"Emergent Auth (built-in)","icon":"lock"}],"groups":[]},{"group":"AI","pages":[{"page":"openai","title":"OpenAI","icon":"sparkles"},{"page":"claude","title":"Claude","icon":"sparkles"},{"page":"gemini","title":"Gemini","icon":"sparkles"}],"groups":[]},{"group":"Messaging & email","pages":[{"page":"twilio","title":"Twilio","icon":"mail"},{"page":"resend","title":"Resend","icon":"mail"},{"page":"sendgrid","title":"SendGrid","icon":"mail"}],"groups":[]},{"group":"Media & productivity","pages":[{"page":"elevenlabs","title":"ElevenLabs","icon":"image"},{"page":"ai-media-generation-image-video-audio","title":"AI media generation (image/video/audio)","icon":"sparkles"},{"page":"shopify","title":"Shopify","icon":"layout-grid"}],"groups":[]},{"group":"GitHub integration","pages":[],"groups":[]},{"group":"Storage","pages":[{"page":"file-storage-emergent-object-store","title":"File storage (Emergent Object Store)","icon":"database"}],"groups":[]}]},{"id":"troubleshooting","label":"Troubleshooting","icon":"wrench","groups":[{"group":"Common Issues","pages":[{"page":"design-inconsistencies","title":"Design inconsistencies","icon":"palette"},{"page":"missing-functionality","title":"Missing functionality","icon":"puzzle"},{"page":"deployment-issues","title":"Publishing issues","icon":"rocket"},{"page":"deployment-pipeline-failures","title":"Publishing pipeline failures","icon":"rocket"},{"page":"works-in-preview-but-breaks-in-production","title":"Works in preview but breaks in production","icon":"eye"},{"page":"app-slow-crashing-or-cold-starting","title":"App slow, crashing or cold-starting","icon":"gauge"}],"groups":[]},{"group":"Reference","pages":[{"page":"glossary-of-emergent-terms","title":"Glossary of Emergent terms","icon":"book-open"},{"page":"faqs","title":"FAQs","icon":"help-circle"}],"groups":[]}]},{"id":"data-trust-support","label":"Data, Trust & Support","icon":"shield","groups":[{"group":"Data & Trust","pages":[{"page":"privacy-gdpr-overview"},{"page":"data-processing-agreement"},{"page":"where-your-data-is-stored"},{"page":"ai-model-training"},{"page":"deletion-retention"},{"page":"controller-responsibilities"},{"page":"security-breach-audit"},{"page":"your-data-ownership"}],"groups":[]},{"group":"Support","pages":[{"page":"getting-help-support-community","title":"Getting help, support & community","icon":"mail"},{"page":"account-security-login","title":"Account security & login","icon":"lock"},{"page":"app-takedown-content-moderation","title":"App takedown & content moderation","icon":"shield"}],"groups":[]}]},{"id":"wingman","label":"Wingman","icon":"robot","groups":[{"group":"Wingman","pages":[{"page":"what-is-wingman"},{"page":"channels-web-telegram-whatsapp-imessage-slack"},{"page":"integrations-scheduled-tasks"},{"page":"custom-mcp-integrations"}],"groups":[]}]}]},"logo_height":28},"documents":[{"id":"dc89cafb-42fd-4cee-95da-946d3fe1d5c5","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"controller-responsibilities","title":"Your responsibilities as a controller","content":"## Your responsibilities as a controller\n\nWhen you build an app on Emergent, **you are the controller** for the personal data your app collects from its end users, and **Emergent is the processor** for that data. This page covers the four situations where that distinction matters: an end user exercising their rights, special category data, a regulator enquiry, and a government or law-enforcement request.\n\n## Data subject rights (your end users)\n\n<Callout type=\"info\" title=\"How we support you\">\nTaking into account the nature of the processing, Emergent **assists you** in fulfilling your obligation to respond to data-subject rights requests (DPA Section 7.2). \n</Callout>\n\n### If an end user contacts Emergent directly\n\nWe will not respond to their request other than to **redirect them to you**, and we'll notify you **without undue delay** (DPA Section 7.3).\n\n<Note>\nRequests about your app's end users should come to you first. For help coordinating a response, contact **privacy@emergent.sh**.\n</Note>\n\n## Special category data\n\nThe Services are **not designed for special category data** (for example health, children's or biometric data), and none is requested or required.\n\nAny such data is submitted **at your election** and is subject to **Clause 4.6 of the DPA** (see **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**).\n\n<Warning>\nIf your app handles special category data, contact **privacy@emergent.sh** before you build, these cases need a closer look rather than a standard answer.\n</Warning>\n\nEmergent does not currently offer a **Business Associate Agreement (BAA)** or special terms for HIPAA-regulated workloads. If your app would process protected health information, contact **privacy@emergent.sh** before you build.\n\n## Regulators & supervisory authorities\n\nEmergent will **promptly notify you** of any measure taken or investigation conducted by a supervisory authority in respect of the processing, and will **cooperate** with them under **Article 31 GDPR** (DPA Section 7.5).\n\n<Note>\nIf you receive a regulator enquiry that touches data processed by Emergent, contact **privacy@emergent.sh** and we'll help coordinate.\n</Note>\n\n## Government & law-enforcement requests\n\nEmergent will **not disclose your customer data** in response to a request from a government, law-enforcement or intelligence authority **unless legally compelled** to do so. If that happens, we will: (a) inform you of the request unless the law prohibits it, (b) seek to redirect the authority to you, and (c) disclose only the minimum required (DPA Section 9.4). As at the date of the DPA, Emergent has received no such request.","status":"published","deleted_at":null,"published_content":"## Your responsibilities as a controller\n\nWhen you build an app on Emergent, **you are the controller** for the personal data your app collects from its end users, and **Emergent is the processor** for that data. This page covers the four situations where that distinction matters: an end user exercising their rights, special category data, a regulator enquiry, and a government or law-enforcement request.\n\n## Data subject rights (your end users)\n\n<Callout type=\"info\" title=\"How we support you\">\nTaking into account the nature of the processing, Emergent **assists you** in fulfilling your obligation to respond to data-subject rights requests (DPA Section 7.2). \n</Callout>\n\n### If an end user contacts Emergent directly\n\nWe will not respond to their request other than to **redirect them to you**, and we'll notify you **without undue delay** (DPA Section 7.3).\n\n<Note>\nRequests about your app's end users should come to you first. For help coordinating a response, contact **privacy@emergent.sh**.\n</Note>\n\n## Special category data\n\nThe Services are **not designed for special category data** (for example health, children's or biometric data), and none is requested or required.\n\nAny such data is submitted **at your election** and is subject to **Clause 4.6 of the DPA** (see **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**).\n\n<Warning>\nIf your app handles special category data, contact **privacy@emergent.sh** before you build, these cases need a closer look rather than a standard answer.\n</Warning>\n\nEmergent does not currently offer a **Business Associate Agreement (BAA)** or special terms for HIPAA-regulated workloads. If your app would process protected health information, contact **privacy@emergent.sh** before you build.\n\n## Regulators & supervisory authorities\n\nEmergent will **promptly notify you** of any measure taken or investigation conducted by a supervisory authority in respect of the processing, and will **cooperate** with them under **Article 31 GDPR** (DPA Section 7.5).\n\n<Note>\nIf you receive a regulator enquiry that touches data processed by Emergent, contact **privacy@emergent.sh** and we'll help coordinate.\n</Note>\n\n## Government & law-enforcement requests\n\nEmergent will **not disclose your customer data** in response to a request from a government, law-enforcement or intelligence authority **unless legally compelled** to do so. If that happens, we will: (a) inform you of the request unless the law prohibits it, (b) seek to redirect the authority to you, and (c) disclose only the minimum required (DPA Section 9.4). As at the date of the DPA, Emergent has received no such request.","published_title":"Your responsibilities as a controller","published_at":"2026-09-25T07:15:20.949197+00:00","created_at":"2026-09-10T15:43:29.749305+00:00","updated_at":"2026-09-25T07:15:20.949197+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"c83eef51-7f8c-40e6-b9d3-823edbfbb798","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"What is Emergent?","slug":"what-is-emergent","content":"## Welcome to Emergent\n\nEmergent is an **agentic vibecoding platform** where you describe what you want to build in natural language, and AI agents handle the rest - writing code, running tests, and publishing your application.\n\nInstead of writing code line-by-line, you chat with Emergent about your vision. The platform's AI agents translate your intent into working software, manage the technical details, and get your app live.\n\n## How it works\n\n<Steps>\n <Step title=\"Describe your idea\">\n Tell Emergent what you want to build in plain language. No technical knowledge required - just explain the problem you're solving or the experience you want to create.\n </Step>\n\n <Step title=\"AI agents build it\">\n Emergent's agents write the code, set up databases, configure APIs, and handle published app. They work autonomously, making technical decisions and implementing features based on your description.\n </Step>\n\n <Step title=\"Test and iterate\">\n Review the working app, provide feedback, and refine. The agents respond to your notes and requests, making changes until the app matches your vision.\n </Step>\n\n <Step title=\"Publish and scale\">\n Your app goes live with hosting, authentication, databases, and infrastructure managed by the platform. Focus on users and features, not DevOps.\n </Step>\n</Steps>\n\n## Vibecoding vs. traditional development\n\n<Columns cols={2}>\n <Card title=\"Traditional coding\" icon=\"code\">\n - Write every line of code yourself\n - Configure build tools, dependencies, environments\n - Manually test across devices and scenarios\n - Set up hosting, CI/CD, monitoring\n - Debug infrastructure issues\n - Weeks or months to first version\n </Card>\n\n <Card title=\"Vibecoding with Emergent\" icon=\"sparkles\">\n - Describe what you want in chat\n - AI handles implementation details\n - Automated testing and quality checks\n - Instant published app and scaling\n - Infrastructure managed for you\n - Working apps in hours or days\n </Card>\n</Columns>\n\n<Tip title=\"Focus on what, not how\">\nVibecoding means focusing on *what* you want your app to do, not *how* to implement it. Describe features, user flows, and goals - the agents handle the technical execution.\n</Tip>\n\n## What you can build\n\nEmergent supports a wide range of applications, from simple prototypes to production-ready products:\n\n- Mobile and web apps with custom UI/UX\n- AI-powered features and workflows\n- Database-backed services with authentication\n- API integrations and third-party connections\n- Media-rich experiences with images, video, and audio\n\n<Info>\nLearn more about the types of apps you can create in [What kind of apps you can build?](/what-kind-of-apps-you-can-build)\n</Info>\n\n## Built-in capabilities\n\nEmergent provides essential platform features out of the box:\n\n- **[Authentication](/emergent-auth-built-in)** - User sign-up, login, and session management\n- **[Database](/database-mongodb)** - MongoDB storage with automatic schema management\n- **[AI integrations](/the-universal-llm-key)** - Access to LLMs, image generation, and more\n- [Media generation](/ai-media-generation-image-video-audio) - Create images, video, and audio with AI\n- **[Custom domains](/custom-domain)** - Publish apps on your own domain\n- **[Wingman assistant](/what-is-wingman)** - AI personal assistant for you as the builder\n\n## Getting started\n\n<CardGroup cols={2}>\n <Card title=\"Explore the workspace\" icon=\"compass\" href=\"/a-tour-of-the-workspace\">\n Take a tour of Emergent's interface and key features\n </Card>\n\n <Card title=\"Understand Jobs\" icon=\"briefcase\" href=\"/what-is-a-job\">\n Learn how AI agents organize and execute work\n </Card>\n\n <Card title=\"Browse the glossary\" icon=\"book-open\" href=\"/glossary-of-emergent-terms\">\n Familiarize yourself with platform terminology\n </Card>\n\n <Card title=\"What and How framework\" icon=\"lightbulb\" href=\"/what-and-how\">\n Master the art of describing your vision effectively\n </Card>\n</CardGroup>\n\n<Note>\nEmergent handles the complexity of modern software development - publishing pipelines, database migrations, API configuration, testing - so you can focus on creating value for your users.\n</Note>","order":0,"parent_id":null,"icon":"book","description":"What is Emergent?","created_at":"2026-09-02T16:17:41.219080+00:00","updated_at":"2026-09-22T06:20:03.950390+00:00","published_at":"2026-09-22T06:20:03.950390+00:00","published_content":"## Welcome to Emergent\n\nEmergent is an **agentic vibecoding platform** where you describe what you want to build in natural language, and AI agents handle the rest - writing code, running tests, and publishing your application.\n\nInstead of writing code line-by-line, you chat with Emergent about your vision. The platform's AI agents translate your intent into working software, manage the technical details, and get your app live.\n\n## How it works\n\n<Steps>\n <Step title=\"Describe your idea\">\n Tell Emergent what you want to build in plain language. No technical knowledge required - just explain the problem you're solving or the experience you want to create.\n </Step>\n\n <Step title=\"AI agents build it\">\n Emergent's agents write the code, set up databases, configure APIs, and handle published app. They work autonomously, making technical decisions and implementing features based on your description.\n </Step>\n\n <Step title=\"Test and iterate\">\n Review the working app, provide feedback, and refine. The agents respond to your notes and requests, making changes until the app matches your vision.\n </Step>\n\n <Step title=\"Publish and scale\">\n Your app goes live with hosting, authentication, databases, and infrastructure managed by the platform. Focus on users and features, not DevOps.\n </Step>\n</Steps>\n\n## Vibecoding vs. traditional development\n\n<Columns cols={2}>\n <Card title=\"Traditional coding\" icon=\"code\">\n - Write every line of code yourself\n - Configure build tools, dependencies, environments\n - Manually test across devices and scenarios\n - Set up hosting, CI/CD, monitoring\n - Debug infrastructure issues\n - Weeks or months to first version\n </Card>\n\n <Card title=\"Vibecoding with Emergent\" icon=\"sparkles\">\n - Describe what you want in chat\n - AI handles implementation details\n - Automated testing and quality checks\n - Instant published app and scaling\n - Infrastructure managed for you\n - Working apps in hours or days\n </Card>\n</Columns>\n\n<Tip title=\"Focus on what, not how\">\nVibecoding means focusing on *what* you want your app to do, not *how* to implement it. Describe features, user flows, and goals - the agents handle the technical execution.\n</Tip>\n\n## What you can build\n\nEmergent supports a wide range of applications, from simple prototypes to production-ready products:\n\n- Mobile and web apps with custom UI/UX\n- AI-powered features and workflows\n- Database-backed services with authentication\n- API integrations and third-party connections\n- Media-rich experiences with images, video, and audio\n\n<Info>\nLearn more about the types of apps you can create in [What kind of apps you can build?](/what-kind-of-apps-you-can-build)\n</Info>\n\n## Built-in capabilities\n\nEmergent provides essential platform features out of the box:\n\n- **[Authentication](/emergent-auth-built-in)** - User sign-up, login, and session management\n- **[Database](/database-mongodb)** - MongoDB storage with automatic schema management\n- **[AI integrations](/the-universal-llm-key)** - Access to LLMs, image generation, and more\n- [Media generation](/ai-media-generation-image-video-audio) - Create images, video, and audio with AI\n- **[Custom domains](/custom-domain)** - Publish apps on your own domain\n- **[Wingman assistant](/what-is-wingman)** - AI personal assistant for you as the builder\n\n## Getting started\n\n<CardGroup cols={2}>\n <Card title=\"Explore the workspace\" icon=\"compass\" href=\"/a-tour-of-the-workspace\">\n Take a tour of Emergent's interface and key features\n </Card>\n\n <Card title=\"Understand Jobs\" icon=\"briefcase\" href=\"/what-is-a-job\">\n Learn how AI agents organize and execute work\n </Card>\n\n <Card title=\"Browse the glossary\" icon=\"book-open\" href=\"/glossary-of-emergent-terms\">\n Familiarize yourself with platform terminology\n </Card>\n\n <Card title=\"What and How framework\" icon=\"lightbulb\" href=\"/what-and-how\">\n Master the art of describing your vision effectively\n </Card>\n</CardGroup>\n\n<Note>\nEmergent handles the complexity of modern software development - publishing pipelines, database migrations, API configuration, testing - so you can focus on creating value for your users.\n</Note>","published_title":"What is Emergent?","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"01bd7a69-41bc-48ba-bca4-0cef4a2d5a56","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"What kind of apps you can build?","slug":"what-kind-of-apps-you-can-build","content":"## Overview\n\nEmergent is a general-purpose platform for building production-ready applications. Whether you're prototyping an idea, shipping an internal dashboard, or publishing a customer-facing SaaS product, Emergent's agentic workflow handles the full stack - frontend, backend, database, hosting, and published app.\n\nYou describe what you want in chat. The platform's AI agents write the code, test it, and publish it live. No frameworks to learn, no infrastructure to configure.\n\n<Callout type=\"tip\" title=\"Not just prototypes\">\nEmergent apps are real, production-grade projects. You get a live URL, custom domains, database persistence, and the ability to iterate continuously as your needs evolve.\n</Callout>\n\n---\n\n## For Individuals\n\nPerfect for personal projects, creative experiments, and side hustles.\n\n**Common use cases:**\n\n- **Portfolios & personal websites** - showcase your work with a custom design and domain\n- **Habit trackers & productivity tools** - build exactly the tracker you need, tailored to your workflow\n- **Learning projects** - test ideas, experiment with features, iterate without setup overhead\n- **Content hubs** - blogs, newsletters, link-in-bio pages\n- **Micro-SaaS MVPs** - validate a product idea before committing to a full build\n\nAll apps come with built-in hosting and a live URL. Add a [custom domain](/custom-domain) to make it truly yours.\n\n---\n\n## For Small & Medium Businesses\n\nEmergent helps teams ship tools faster - without hiring a dev team or waiting months for an agency.\n\n**Common use cases:**\n\n- **Internal dashboards** - visualize KPIs, track operations, manage workflows\n- **Customer portals** - let clients view orders, book appointments, submit requests\n- **CRM & lead management** - custom tools that fit your sales process\n- **E-commerce storefronts** - product catalogs, checkout flows, order tracking\n- **Event & booking platforms** - handle registrations, payments, scheduling\n- **Marketing landing pages** - quickly spin up campaign-specific pages with forms and analytics\n\n<Info>\nTeams often start with a simple MVP in Emergent, then expand it iteratively as they learn what works. The same app can evolve from a prototype to a production workhorse without platform migration.\n</Info>\n\nIntegration with third-party services (Stripe, Twilio, analytics providers) is straightforward - just describe the integration you need. See [Custom & MCP integrations](/custom-mcp-integrations) for details.\n\n---\n\n## For Enterprises\n\nEmergent supports complex, multi-user applications with authentication, role-based access, and scalable architecture.\n\n**Common use cases:**\n\n- **Enterprise dashboards & reporting tools** - aggregate data from multiple sources, support large user bases\n- **Workflow automation platforms** - custom approval chains, ticket systems, process management\n- **Customer-facing SaaS products** - multi-tenant apps with user accounts, billing, analytics\n- **Data collection & admin panels** - manage large datasets, moderate content, enforce compliance\n- **White-label platforms** - publish customized instances for different clients or regions\n\n<CardGroup cols={2}>\n <Card title=\"Persistent database\" icon=\"database\">\n Every app includes a MongoDB instance for structured data persistence. See [Database (MongoDB)](/database-mongodb).\n </Card>\n <Card title=\"Custom agents\" icon=\"wand-sparkles\">\n Extend the platform's capabilities with domain-specific logic. See [Custom agents](/custom-agents).\n </Card>\n</CardGroup>\n\n<Warning title=\"Performance at scale\">\nIf your app handles high traffic or compute-intensive tasks, monitor performance early. See [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) for optimization guidance.\n</Warning>\n\n---\n\n## Mobile & Cross-Platform\n\nEmergent builds both web and mobile apps. Conversion between the two works in one direction only: Web to mobile: available as a fork. The fork creates a new mobile job with the same backend. You will have the option to choose the nature of the forked job - to keep it as a web app or switch to a mobile app. The original web job keeps its own type and stays unchanged. Mobile to web: not supported. Start a new web job and rebuild it, using the mobile app as a reference. A job's app type never changes in place — conversion always creates a separate job, never an in-place switch.\n\n- **Native mobile apps** - iOS and Android from a single codebase\n- **Responsive web apps** - optimized for desktop, tablet, and mobile browsers\n\n- **Progressive Web Apps (PWAs)** - installable, offline-capable web experiences\n\n<Tip>\nDescribe \"make this mobile-friendly\" in chat to adjust the UI and interactions. To convert a web app to a native mobile app, use the preview toggle or Publish panel \"Add Mobile App\" option, this forks your project into a new mobile job sharing the same backend. Note that mobile-to-web conversion is not available. Learn more: [Web to Mobile conversion](/web-mobile-conversion-canonical).\n</Tip>\n\n---\n\n## What's Next\n\n<Steps>\n <Step title=\"Explore the workspace\">\n Get familiar with the chat interface, preview pane, and published app controls. See [A tour of the workspace](/a-tour-of-the-workspace).\n </Step>\n <Step title=\"Start building\">\n Describe your first app in chat. Be as detailed or high-level as you like - agents will ask clarifying questions.\n </Step>\n <Step title=\"Publish & iterate\">\n Once you're happy with the preview, publish live. You can continue refining in chat even after launch.\n </Step>\n</Steps>\n\n<Callout type=\"info\">\nNot sure where to start? Browse the [Glossary of Emergent terms](/glossary-of-emergent-terms) to understand key concepts, or jump straight into chat and describe what you want to build.\n</Callout>\n\n\n---\n\n## What each app type can use: database & APIs\n\nDifferent app types get different backend capabilities:\n\n| App type | Built-in MongoDB | External API access |\n|---|---|---|\n| **Full Stack App** | Yes - built-in MongoDB (or connect an external database) | Yes - call any third-party API from the backend |\n| **Mobile App (Expo/React Native)** | Yes - built-in MongoDB via its **server-side backend** (shared across platforms; separate preview & production databases), plus offline-first local storage on-device | Yes - external API calls go through that same backend |\n| **Landing Page** | Yes - built-in MongoDB  | Yes - call any third-party API  |\n\n<Note>\nFull Stack Apps and Landing Pages publish to a web URL; Mobile Apps build with Expo/React Native and ship through the app stores. A Full Stack App can be converted to a Mobile App (one-way) so both share the same backend. Mobile database/API behaviour: see [Database & data on mobile](/database-data-on-mobile).\n</Note>\n","order":1,"parent_id":null,"icon":"lightbulb","description":"Full-stack web apps, mobile apps, landing pages, MVPs, dashboards, internal tools, e-commerce - projects of any scale.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:03.955309+00:00","published_at":"2026-09-22T06:20:03.955309+00:00","published_content":"## Overview\n\nEmergent is a general-purpose platform for building production-ready applications. Whether you're prototyping an idea, shipping an internal dashboard, or publishing a customer-facing SaaS product, Emergent's agentic workflow handles the full stack - frontend, backend, database, hosting, and published app.\n\nYou describe what you want in chat. The platform's AI agents write the code, test it, and publish it live. No frameworks to learn, no infrastructure to configure.\n\n<Callout type=\"tip\" title=\"Not just prototypes\">\nEmergent apps are real, production-grade projects. You get a live URL, custom domains, database persistence, and the ability to iterate continuously as your needs evolve.\n</Callout>\n\n---\n\n## For Individuals\n\nPerfect for personal projects, creative experiments, and side hustles.\n\n**Common use cases:**\n\n- **Portfolios & personal websites** - showcase your work with a custom design and domain\n- **Habit trackers & productivity tools** - build exactly the tracker you need, tailored to your workflow\n- **Learning projects** - test ideas, experiment with features, iterate without setup overhead\n- **Content hubs** - blogs, newsletters, link-in-bio pages\n- **Micro-SaaS MVPs** - validate a product idea before committing to a full build\n\nAll apps come with built-in hosting and a live URL. Add a [custom domain](/custom-domain) to make it truly yours.\n\n---\n\n## For Small & Medium Businesses\n\nEmergent helps teams ship tools faster - without hiring a dev team or waiting months for an agency.\n\n**Common use cases:**\n\n- **Internal dashboards** - visualize KPIs, track operations, manage workflows\n- **Customer portals** - let clients view orders, book appointments, submit requests\n- **CRM & lead management** - custom tools that fit your sales process\n- **E-commerce storefronts** - product catalogs, checkout flows, order tracking\n- **Event & booking platforms** - handle registrations, payments, scheduling\n- **Marketing landing pages** - quickly spin up campaign-specific pages with forms and analytics\n\n<Info>\nTeams often start with a simple MVP in Emergent, then expand it iteratively as they learn what works. The same app can evolve from a prototype to a production workhorse without platform migration.\n</Info>\n\nIntegration with third-party services (Stripe, Twilio, analytics providers) is straightforward - just describe the integration you need. See [Custom & MCP integrations](/custom-mcp-integrations) for details.\n\n---\n\n## For Enterprises\n\nEmergent supports complex, multi-user applications with authentication, role-based access, and scalable architecture.\n\n**Common use cases:**\n\n- **Enterprise dashboards & reporting tools** - aggregate data from multiple sources, support large user bases\n- **Workflow automation platforms** - custom approval chains, ticket systems, process management\n- **Customer-facing SaaS products** - multi-tenant apps with user accounts, billing, analytics\n- **Data collection & admin panels** - manage large datasets, moderate content, enforce compliance\n- **White-label platforms** - publish customized instances for different clients or regions\n\n<CardGroup cols={2}>\n <Card title=\"Persistent database\" icon=\"database\">\n Every app includes a MongoDB instance for structured data persistence. See [Database (MongoDB)](/database-mongodb).\n </Card>\n <Card title=\"Custom agents\" icon=\"wand-sparkles\">\n Extend the platform's capabilities with domain-specific logic. See [Custom agents](/custom-agents).\n </Card>\n</CardGroup>\n\n<Warning title=\"Performance at scale\">\nIf your app handles high traffic or compute-intensive tasks, monitor performance early. See [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) for optimization guidance.\n</Warning>\n\n---\n\n## Mobile & Cross-Platform\n\nEmergent builds both web and mobile apps. Conversion between the two works in one direction only: Web to mobile: available as a fork. The fork creates a new mobile job with the same backend. You will have the option to choose the nature of the forked job - to keep it as a web app or switch to a mobile app. The original web job keeps its own type and stays unchanged. Mobile to web: not supported. Start a new web job and rebuild it, using the mobile app as a reference. A job's app type never changes in place — conversion always creates a separate job, never an in-place switch.\n\n- **Native mobile apps** - iOS and Android from a single codebase\n- **Responsive web apps** - optimized for desktop, tablet, and mobile browsers\n\n- **Progressive Web Apps (PWAs)** - installable, offline-capable web experiences\n\n<Tip>\nDescribe \"make this mobile-friendly\" in chat to adjust the UI and interactions. To convert a web app to a native mobile app, use the preview toggle or Publish panel \"Add Mobile App\" option, this forks your project into a new mobile job sharing the same backend. Note that mobile-to-web conversion is not available. Learn more: [Web to Mobile conversion](/web-mobile-conversion-canonical).\n</Tip>\n\n---\n\n## What's Next\n\n<Steps>\n <Step title=\"Explore the workspace\">\n Get familiar with the chat interface, preview pane, and published app controls. See [A tour of the workspace](/a-tour-of-the-workspace).\n </Step>\n <Step title=\"Start building\">\n Describe your first app in chat. Be as detailed or high-level as you like - agents will ask clarifying questions.\n </Step>\n <Step title=\"Publish & iterate\">\n Once you're happy with the preview, publish live. You can continue refining in chat even after launch.\n </Step>\n</Steps>\n\n<Callout type=\"info\">\nNot sure where to start? Browse the [Glossary of Emergent terms](/glossary-of-emergent-terms) to understand key concepts, or jump straight into chat and describe what you want to build.\n</Callout>\n\n\n---\n\n## What each app type can use: database & APIs\n\nDifferent app types get different backend capabilities:\n\n| App type | Built-in MongoDB | External API access |\n|---|---|---|\n| **Full Stack App** | Yes - built-in MongoDB (or connect an external database) | Yes - call any third-party API from the backend |\n| **Mobile App (Expo/React Native)** | Yes - built-in MongoDB via its **server-side backend** (shared across platforms; separate preview & production databases), plus offline-first local storage on-device | Yes - external API calls go through that same backend |\n| **Landing Page** | Yes - built-in MongoDB  | Yes - call any third-party API  |\n\n<Note>\nFull Stack Apps and Landing Pages publish to a web URL; Mobile Apps build with Expo/React Native and ship through the app stores. A Full Stack App can be converted to a Mobile App (one-way) so both share the same backend. Mobile database/API behaviour: see [Database & data on mobile](/database-data-on-mobile).\n</Note>\n","published_title":"What kind of apps you can build?","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"3b30a473-c1f5-435c-9616-22ae5dcf66ef","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"The chat-to-publish flow","slug":"the-chat-to-deployment-flow","content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Overview\n\nEmergent transforms natural-language descriptions into published applications through a five-phase workflow. You describe what you want in chat, AI agents write and test the code, you preview the result in real time, iterate until it's right, and then publish to production - all without leaving the platform.\n\nThis page walks through the complete arc from your first prompt to a live URL.\n\n---\n\n## The five phases\n\n**Each stage, in depth on the Learn the Basics path:** [Watch your app come alive](/watch-your-app-come-alive) · [Previewing & iterating](/previewing-iterating) · [Try it before you share it](/try-it-before-you-share-it) · [Put your app live](/put-your-app-live).\n\n<Steps>\n\n<Step title=\"Prompt: Describe your app\">\n\nStart a conversation in the Emergent chat interface (web or [mobile](/building-from-the-emergent-mobile-app)). Write what you want to build in plain language:\n\n- **Simple apps**: \"A to-do list with tags and due dates\"\n- **Data-driven tools**: \"A CRM that tracks customer interactions and sends email reminders\"\n- **Consumer products**: \"A recipe sharing app where users can save favorites and comment\"\n\nThe AI agents parse your intent, ask clarifying questions if needed, and generate a technical plan. You don't need to specify frameworks, libraries, or architecture - the platform selects the stack automatically.\n\n<Tip title=\"Start broad, then refine\">\nYou'll have many chances to iterate. Begin with the core idea; worry about styling and edge cases later.\n</Tip>\n\n</Step>\n\n<Step title=\"Build: Agents write, test and wire everything\">\n\nOnce you confirm the plan (or the agents infer enough confidence), code generation begins:\n\n- **Backend services** (API routes, database schemas, authentication) are scaffolded and connected.\n- **Frontend UI** (React components, navigation, forms) is generated with responsive design patterns.\n- **Integrations** (email, payment APIs, third-party SDKs) are wired in when requested.\n- **Tests** run automatically to catch regressions before you see the preview.\n\nThe build typically completes in seconds to a few minutes, depending on app complexity. You'll see live progress in the chat and a status indicator in the [workspace](/a-tour-of-the-workspace).\n\n</Step>\n\n<Step title=\"Preview: Interact with the running app\">\n\nAs soon as the build succeeds, Emergent spins up a **preview environment** - a fully functional instance of your app at a temporary URL. You can:\n\n- Click through every screen and flow.\n- Create test accounts, submit forms, trigger workflows.\n- Open the preview on desktop, tablet, or phone to verify responsive behavior.\n\nThe preview environment includes live databases, auth, and any third-party integrations you've configured (using sandbox/test keys when appropriate). It's isolated from production, so you can experiment freely.\n\n<Info>\nPreview environments sleep after 30 minutes of inactivity; preview links are session-dependent. You can share the preview URL with teammates or stakeholders for feedback.\n</Info>\n\nLearn more about the [separation between preview and published instances](/preview-vs-deployed-separate).\n\n</Step>\n\n<Step title=\"Iterate: Refine in natural language\">\n\nSpot a bug? Want a different layout? Return to the chat and describe the change:\n\n- \"Make the search bar sticky at the top\"\n- \"Add a dark mode toggle in settings\"\n- \"Fix the email validation - it's rejecting valid addresses\"\n\nThe AI agents apply the edits incrementally, re-run tests, and refresh the preview. You can iterate as many times as needed. Each change is version-controlled, so you can roll back if something breaks.\n\n<Tip title=\"Use screenshots and screen recordings\">\nPaste images or link to videos in chat to show exactly what needs fixing. The agents understand visual context.\n</Tip>\n\n</Step>\n\n<Step title=\"Publish: Push to production\">\n\nWhen you're satisfied with the preview, click **Publish** in the workspace. Emergent:\n\n1. Provisions production infrastructure (databases, storage, CDN).\n2. Applies environment-specific configuration (production API keys, domain settings).\n3. Runs health checks to confirm the app is responding correctly.\n4. Publishes the app to a live, autoscaling environment.\n\nYour app is assigned a default `<appname>.emergent.host` URL immediately. You can [map a custom domain](/custom-domain) anytime after published app.\n\n<Warning title=\"Preview and production are separate\">\nData, user accounts, and integrations in preview **do not** carry over to production( except for the very first publish). Plan your production setup (real API keys, payment processors, etc.) before the first publish.\n</Warning>\n\n</Step>\n\n</Steps>\n\n---\n\n## Key concepts to know\n\n| Concept | What it means |\n|---------|---------------|\n| **Workspace** | The central hub where you manage builds, previews, and published versions. See [a tour of the workspace](/a-tour-of-the-workspace). |\n| **Preview environment** | A temporary, fully functional instance for testing. Isolated from production. |\n| **Published instance** | Your production app, live at a public URL with real users and data. |\n| **Universal LLM Key** | A single API key that routes to multiple LLM providers (OpenAI, Anthropic, etc.). Optional; custom provider keys are also supported. See [the Universal LLM Key](/the-universal-llm-key). |\n| **Emergent Auth** | Built-in user authentication (email/password, Google sign-in). No third-party auth service needed. See [Emergent Auth](/emergent-auth-built-in). |\n\nBrowse the full [glossary of Emergent terms](/glossary-of-emergent-terms) for more definitions.\n\n> **Building a mobile app?** The chat-to-store flow adds a native build and app-store review on top of this. See [Building from your phone](/building-from-the-emergent-mobile-app) and [Publishing to the stores](/publishing-to-the-stores).\n","order":2,"parent_id":null,"icon":"rocket","description":"The big-picture arc of building on Emergent: prompt -> build -> preview -> iterate -> deploy. A map of the whole journey before diving in.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:07:36.457387+00:00","published_at":"2026-10-05T14:07:36.457387+00:00","published_content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Overview\n\nEmergent transforms natural-language descriptions into published applications through a five-phase workflow. You describe what you want in chat, AI agents write and test the code, you preview the result in real time, iterate until it's right, and then publish to production - all without leaving the platform.\n\nThis page walks through the complete arc from your first prompt to a live URL.\n\n---\n\n## The five phases\n\n**Each stage, in depth on the Learn the Basics path:** [Watch your app come alive](/watch-your-app-come-alive) · [Previewing & iterating](/previewing-iterating) · [Try it before you share it](/try-it-before-you-share-it) · [Put your app live](/put-your-app-live).\n\n<Steps>\n\n<Step title=\"Prompt: Describe your app\">\n\nStart a conversation in the Emergent chat interface (web or [mobile](/building-from-the-emergent-mobile-app)). Write what you want to build in plain language:\n\n- **Simple apps**: \"A to-do list with tags and due dates\"\n- **Data-driven tools**: \"A CRM that tracks customer interactions and sends email reminders\"\n- **Consumer products**: \"A recipe sharing app where users can save favorites and comment\"\n\nThe AI agents parse your intent, ask clarifying questions if needed, and generate a technical plan. You don't need to specify frameworks, libraries, or architecture - the platform selects the stack automatically.\n\n<Tip title=\"Start broad, then refine\">\nYou'll have many chances to iterate. Begin with the core idea; worry about styling and edge cases later.\n</Tip>\n\n</Step>\n\n<Step title=\"Build: Agents write, test and wire everything\">\n\nOnce you confirm the plan (or the agents infer enough confidence), code generation begins:\n\n- **Backend services** (API routes, database schemas, authentication) are scaffolded and connected.\n- **Frontend UI** (React components, navigation, forms) is generated with responsive design patterns.\n- **Integrations** (email, payment APIs, third-party SDKs) are wired in when requested.\n- **Tests** run automatically to catch regressions before you see the preview.\n\nThe build typically completes in seconds to a few minutes, depending on app complexity. You'll see live progress in the chat and a status indicator in the [workspace](/a-tour-of-the-workspace).\n\n</Step>\n\n<Step title=\"Preview: Interact with the running app\">\n\nAs soon as the build succeeds, Emergent spins up a **preview environment** - a fully functional instance of your app at a temporary URL. You can:\n\n- Click through every screen and flow.\n- Create test accounts, submit forms, trigger workflows.\n- Open the preview on desktop, tablet, or phone to verify responsive behavior.\n\nThe preview environment includes live databases, auth, and any third-party integrations you've configured (using sandbox/test keys when appropriate). It's isolated from production, so you can experiment freely.\n\n<Info>\nPreview environments sleep after 30 minutes of inactivity; preview links are session-dependent. You can share the preview URL with teammates or stakeholders for feedback.\n</Info>\n\nLearn more about the [separation between preview and published instances](/preview-vs-deployed-separate).\n\n</Step>\n\n<Step title=\"Iterate: Refine in natural language\">\n\nSpot a bug? Want a different layout? Return to the chat and describe the change:\n\n- \"Make the search bar sticky at the top\"\n- \"Add a dark mode toggle in settings\"\n- \"Fix the email validation - it's rejecting valid addresses\"\n\nThe AI agents apply the edits incrementally, re-run tests, and refresh the preview. You can iterate as many times as needed. Each change is version-controlled, so you can roll back if something breaks.\n\n<Tip title=\"Use screenshots and screen recordings\">\nPaste images or link to videos in chat to show exactly what needs fixing. The agents understand visual context.\n</Tip>\n\n</Step>\n\n<Step title=\"Publish: Push to production\">\n\nWhen you're satisfied with the preview, click **Publish** in the workspace. Emergent:\n\n1. Provisions production infrastructure (databases, storage, CDN).\n2. Applies environment-specific configuration (production API keys, domain settings).\n3. Runs health checks to confirm the app is responding correctly.\n4. Publishes the app to a live, autoscaling environment.\n\nYour app is assigned a default `<appname>.emergent.host` URL immediately. You can [map a custom domain](/custom-domain) anytime after published app.\n\n<Warning title=\"Preview and production are separate\">\nData, user accounts, and integrations in preview **do not** carry over to production( except for the very first publish). Plan your production setup (real API keys, payment processors, etc.) before the first publish.\n</Warning>\n\n</Step>\n\n</Steps>\n\n---\n\n## Key concepts to know\n\n| Concept | What it means |\n|---------|---------------|\n| **Workspace** | The central hub where you manage builds, previews, and published versions. See [a tour of the workspace](/a-tour-of-the-workspace). |\n| **Preview environment** | A temporary, fully functional instance for testing. Isolated from production. |\n| **Published instance** | Your production app, live at a public URL with real users and data. |\n| **Universal LLM Key** | A single API key that routes to multiple LLM providers (OpenAI, Anthropic, etc.). Optional; custom provider keys are also supported. See [the Universal LLM Key](/the-universal-llm-key). |\n| **Emergent Auth** | Built-in user authentication (email/password, Google sign-in). No third-party auth service needed. See [Emergent Auth](/emergent-auth-built-in). |\n\nBrowse the full [glossary of Emergent terms](/glossary-of-emergent-terms) for more definitions.\n\n> **Building a mobile app?** The chat-to-store flow adds a native build and app-store review on top of this. See [Building from your phone](/building-from-the-emergent-mobile-app) and [Publishing to the stores](/publishing-to-the-stores).\n","published_title":"The chat-to-publish flow","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"3345931a-0098-4cf0-b194-09cb3f5bf34e","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"How apps work here","slug":"how-apps-work-here-mental-model","content":"## You describe, the agent builds\n\nWhen you work with Emergent, you're collaborating with an AI agent that handles all the implementation details. Here's how the division of labor works:\n\n**What the agent handles:**\n\n- Writing all code (Python backend, React frontend, database schemas)\n- Setting up project structure and dependencies\n- Following web development best practices\n- Fixing bugs and runtime errors\n- Publishing and configuring infrastructure\n\n**What you decide:**\n\n- The app's purpose and core features\n- User experience and interface choices\n- Business logic and workflows\n- When a feature is \"done\"\n- Which direction to take when multiple options exist\n\n<Tip title=\"Think of it as pair programming\">\nYou're the product owner and architect; the agent is the developer who implements your vision. The clearer your requirements, the better the result.\n</Tip>\n\nThis model lets you focus on *what* you want to build rather than *how* to build it. The agent translates your natural-language descriptions into working code, tests it, and publishes it - often in a single conversation.\n\nFor a concrete example of this workflow in action, see [Your first build (walkthrough)](/start-with-your-idea).\n\n## What's under the hood\n\nEmergent apps are full-stack web applications, and the technology stack varies by template. The most common stack uses:\n\n- **Backend**: FastAPI (Python) - handles API endpoints, business logic, and data operations\n- **Frontend**: React - renders the user interface and manages client-side state\n- **Database**: MongoDB - stores your application data with flexible schemas\n\nHowever, the stack depends on which template you choose. For example, Next.js projects use their own API routes instead of a separate FastAPI backend; the Python-only template has no frontend or MongoDB; and Mobile App projects are built with Expo/React Native.\n\n<Info title=\"Why this matters\">\nUnderstanding the stack helps you communicate more effectively with the agent. When you say \"add a REST endpoint\" or \"create a new collection,\" the agent knows exactly what you mean in the context of your chosen template's stack.\n</Info>\n\nYou don't need to write any of this code yourself, but knowing the foundation helps in a few situations:\n\n- **Debugging**: When something doesn't work, you can describe the problem using technical terms the agent understands\n- **Integrations**: If you want to connect external services, you'll know what capabilities the stack provides\n- **Migration**: If you ever need to export your app, you'll have a standard codebase built on your chosen template's frameworks\n\nAll code is generated according to modern best practices for each framework. The agent handles package management, routing, state management, and publish configuration automatically.\n\nFor help troubleshooting issues, see [Debugging & testing with the agent](/debugging-testing-with-the-agent).\n\n## What the AI knows vs what you think it knows\n\n<Warning title=\"Common source of frustration\">\nThe agent is powerful, but it cannot read your mind. It only knows what you've explicitly told it in the current conversation.\n</Warning>\n\n**The agent remembers:**\n\n- Everything you've said in the current chat session\n- The current state of your app's code and structure\n- General web development knowledge and best practices\n- Common patterns for similar features\n\nThe agent does NOT automatically know:\n\n- Your industry-specific jargon or internal terminology\n- Implicit requirements you assume are \"obvious\"\n- Visual design preferences unless you describe them\n- Data formats or business rules you haven't mentioned\n- Context from previous projects or other apps\n\n### Being explicit pays off\n\nInstead of: *\"Add the usual authentication\"*\nTry: *\"Add email/password authentication with a login page and signup page. Store user sessions with JWT tokens.\"*\n\nInstead of: *\"Make it look professional\"*\nTry: *\"Use a clean layout with a white background, blue primary buttons, and cards with subtle shadows for each item.\"*\n\nInstead of: *\"Connect to the payment system\"*\nTry: *\"Integrate Stripe for payments. Users should be able to purchase credits with a card, and we need to store transaction history in a `payments` collection.\"*\n\n<Tip>\nWhen the agent asks clarifying questions, it's helping you be more specific. Answering these questions leads to better results faster than assuming the agent will \"figure it out.\"\n</Tip>\n\nThe more concrete and detailed your descriptions, the closer the first implementation will be to your vision. Vague instructions require more back-and-forth to get right.\n\nFor guidance on communicating effectively with the agent, see [Best Practices](/best-practices) and [What and How](/what-and-how).","order":3,"parent_id":null,"icon":"brain","description":"How apps work here (mental model)","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:03.949255+00:00","published_at":"2026-09-22T06:20:03.949255+00:00","published_content":"## You describe, the agent builds\n\nWhen you work with Emergent, you're collaborating with an AI agent that handles all the implementation details. Here's how the division of labor works:\n\n**What the agent handles:**\n\n- Writing all code (Python backend, React frontend, database schemas)\n- Setting up project structure and dependencies\n- Following web development best practices\n- Fixing bugs and runtime errors\n- Publishing and configuring infrastructure\n\n**What you decide:**\n\n- The app's purpose and core features\n- User experience and interface choices\n- Business logic and workflows\n- When a feature is \"done\"\n- Which direction to take when multiple options exist\n\n<Tip title=\"Think of it as pair programming\">\nYou're the product owner and architect; the agent is the developer who implements your vision. The clearer your requirements, the better the result.\n</Tip>\n\nThis model lets you focus on *what* you want to build rather than *how* to build it. The agent translates your natural-language descriptions into working code, tests it, and publishes it - often in a single conversation.\n\nFor a concrete example of this workflow in action, see [Your first build (walkthrough)](/start-with-your-idea).\n\n## What's under the hood\n\nEmergent apps are full-stack web applications, and the technology stack varies by template. The most common stack uses:\n\n- **Backend**: FastAPI (Python) - handles API endpoints, business logic, and data operations\n- **Frontend**: React - renders the user interface and manages client-side state\n- **Database**: MongoDB - stores your application data with flexible schemas\n\nHowever, the stack depends on which template you choose. For example, Next.js projects use their own API routes instead of a separate FastAPI backend; the Python-only template has no frontend or MongoDB; and Mobile App projects are built with Expo/React Native.\n\n<Info title=\"Why this matters\">\nUnderstanding the stack helps you communicate more effectively with the agent. When you say \"add a REST endpoint\" or \"create a new collection,\" the agent knows exactly what you mean in the context of your chosen template's stack.\n</Info>\n\nYou don't need to write any of this code yourself, but knowing the foundation helps in a few situations:\n\n- **Debugging**: When something doesn't work, you can describe the problem using technical terms the agent understands\n- **Integrations**: If you want to connect external services, you'll know what capabilities the stack provides\n- **Migration**: If you ever need to export your app, you'll have a standard codebase built on your chosen template's frameworks\n\nAll code is generated according to modern best practices for each framework. The agent handles package management, routing, state management, and publish configuration automatically.\n\nFor help troubleshooting issues, see [Debugging & testing with the agent](/debugging-testing-with-the-agent).\n\n## What the AI knows vs what you think it knows\n\n<Warning title=\"Common source of frustration\">\nThe agent is powerful, but it cannot read your mind. It only knows what you've explicitly told it in the current conversation.\n</Warning>\n\n**The agent remembers:**\n\n- Everything you've said in the current chat session\n- The current state of your app's code and structure\n- General web development knowledge and best practices\n- Common patterns for similar features\n\nThe agent does NOT automatically know:\n\n- Your industry-specific jargon or internal terminology\n- Implicit requirements you assume are \"obvious\"\n- Visual design preferences unless you describe them\n- Data formats or business rules you haven't mentioned\n- Context from previous projects or other apps\n\n### Being explicit pays off\n\nInstead of: *\"Add the usual authentication\"*\nTry: *\"Add email/password authentication with a login page and signup page. Store user sessions with JWT tokens.\"*\n\nInstead of: *\"Make it look professional\"*\nTry: *\"Use a clean layout with a white background, blue primary buttons, and cards with subtle shadows for each item.\"*\n\nInstead of: *\"Connect to the payment system\"*\nTry: *\"Integrate Stripe for payments. Users should be able to purchase credits with a card, and we need to store transaction history in a `payments` collection.\"*\n\n<Tip>\nWhen the agent asks clarifying questions, it's helping you be more specific. Answering these questions leads to better results faster than assuming the agent will \"figure it out.\"\n</Tip>\n\nThe more concrete and detailed your descriptions, the closer the first implementation will be to your vision. Vague instructions require more back-and-forth to get right.\n\nFor guidance on communicating effectively with the agent, see [Best Practices](/best-practices) and [What and How](/what-and-how).","published_title":"How apps work here","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"23c8b2f7-3aa6-4229-8ed0-bff4219b6273","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"A tour of the workspace","slug":"a-tour-of-the-workspace","content":"## Overview\n\nThe Emergent workspace is divided into five main areas, each handling a distinct part of the build-test-publish cycle. Understanding this layout will help you move quickly from idea to shipped product.\n\n<Callout type=\"tip\" title=\"New to Emergent?\">\nWalk through [Your first build](/start-with-your-idea) to see these panels in action.\n</Callout>\n\n---\n\n## Chat panel\n\nThe **Chat panel** is where you describe your app, request changes, and ask the agent questions. Every message you send triggers the agent to generate or modify code, install dependencies, and refresh the preview.\n\n**Key behaviors:**\n\n- The agent reads your entire conversation history, so you can refer back to earlier instructions.\n- Attach files - screenshots, designs, CSVs, or any other asset - directly in the chat to guide the build. [Learn about file uploads](#uploading-files-and-images).\n- The agent will tell you when it's working, when tests pass, and when the preview is ready.\n\n<Note>\nThe chat is persistent across sessions. Close the workspace and return later; your conversation and build state are saved.\n</Note>\n\n---\n\n## Preview panel\n\nThe **Preview panel** renders a live, interactive view of your application. Every time the agent completes a code change, the preview auto-refreshes so you can immediately see the result.\n\n**What you can do:**\n\n- Click through flows, fill forms, test buttons - treat it like the real app.\n- Open the preview in a new browser tab for a full-screen experience.\n- Use browser DevTools to inspect elements, check network requests, or debug layout issues.\n\n<Warning>\nThe preview runs *in the workspace only*. It is **not** your published application. See [Preview vs Published](/preview-vs-deployed-separate) for the key differences.\n</Warning>\n\n---\n\n## Secrets and environment variables\n\nThe **Secrets / Env area** is where you configure API keys, connection strings, and any other environment variables your app needs.\n\n**Important distinctions:**\n\n- Secrets stored here apply to the **preview** environment. After the first publish, preview and production environment variables are separate; changes made here do not automatically apply to future published versions.\n- They are encrypted at rest and never exposed in the chat or logs.\n- The platform injects a special [Universal LLM Key](/the-universal-llm-key) automatically, so you can call OpenAI, Anthropic, and other LLM providers without adding your own keys during development.\n\n<Tip>\nAdd secrets *before* asking the agent to integrate third-party services. The agent will reference them by name (e.g., `STRIPE_SECRET_KEY`) when generating code.\n</Tip>\n\nLearn more in [Secrets & env variables](/secrets-env-variables).\n\n---\n\n## GitHub controls\n\nThe **GitHub controls** let you save your workspace code to a repository.\n\n**Core actions:**\n\n- **Save to GitHub:** Commit the current state of your workspace to a new or existing repository. This creates a snapshot you can share, review, or roll back to.\n\n<Warning>\nImporting a repo is only possible when starting a new job. There is no pull or in-platform merge available mid-project. See [Save to GitHub](/save-to-github).\n</Warning>\n\nFor step-by-step instructions, see [Save to GitHub](/save-to-github).\n\n---\n\n## Publish controls\n\nThe **Publish controls** are where you ship your application to a live, publicly accessible URL.\n\n**Available actions:**\n\n- **Publish:** Create a new published app from the current workspace state. You'll receive a unique URL that stays live until you delete it.\n- **Re-publish:** Push the latest workspace changes to an *existing* published app, preserving the same URL and published app ID.\n- **Replace:** Swap out the code of a running published app with a different workspace or branch, keeping the same domain and environment.\n\n<Info>\nPublished versions are *separate* from the preview. Each published app gets its own secrets, database, and runtime. [Preview vs Published](/preview-vs-deployed-separate) explains the isolation model.\n</Info>\n\nReview your options in [Publishing types](/deployment-types) and [Publishing plan levels](/deployment-plan-levels).\n\n---\n\n## Uploading files and images\n\nYou can **attach files directly** in the chat panel to guide the agent's work. Common use cases include:\n\n- **Design mockups:** Upload a screenshot or Figma export; the agent will replicate the layout and styling.\n- **Data samples:** Attach a CSV or JSON file; the agent will infer the schema and build import/export flows.\n- **Icons and logos:** Provide brand assets; the agent will reference them in the UI.\n- **Documents:** Share a spec, API response example, or requirements doc; the agent will parse it and apply the details.\n\n**How it works:**\n\n1. Click the attachment icon in the chat input (or drag and drop).\n2. Select one or more files (images, PDFs, spreadsheets, text).\n3. Send your message; the agent processes the files alongside your instructions.\n\n<Tip>\nCombine a screenshot with a short caption like \"Build a dashboard that looks like this\" for fast, accurate results.\n</Tip>\n\nFiles uploaded to the chat are stored temporarily for the agent's use. If your *application* needs persistent file storage (e.g., user uploads), see [File storage (Emergent Object Store)](/file-storage-emergent-object-store).\n","order":4,"parent_id":null,"icon":"layout","description":"1. Chat panel: where you talk to the agent.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:03.959277+00:00","published_at":"2026-09-22T06:20:03.959277+00:00","published_content":"## Overview\n\nThe Emergent workspace is divided into five main areas, each handling a distinct part of the build-test-publish cycle. Understanding this layout will help you move quickly from idea to shipped product.\n\n<Callout type=\"tip\" title=\"New to Emergent?\">\nWalk through [Your first build](/start-with-your-idea) to see these panels in action.\n</Callout>\n\n---\n\n## Chat panel\n\nThe **Chat panel** is where you describe your app, request changes, and ask the agent questions. Every message you send triggers the agent to generate or modify code, install dependencies, and refresh the preview.\n\n**Key behaviors:**\n\n- The agent reads your entire conversation history, so you can refer back to earlier instructions.\n- Attach files - screenshots, designs, CSVs, or any other asset - directly in the chat to guide the build. [Learn about file uploads](#uploading-files-and-images).\n- The agent will tell you when it's working, when tests pass, and when the preview is ready.\n\n<Note>\nThe chat is persistent across sessions. Close the workspace and return later; your conversation and build state are saved.\n</Note>\n\n---\n\n## Preview panel\n\nThe **Preview panel** renders a live, interactive view of your application. Every time the agent completes a code change, the preview auto-refreshes so you can immediately see the result.\n\n**What you can do:**\n\n- Click through flows, fill forms, test buttons - treat it like the real app.\n- Open the preview in a new browser tab for a full-screen experience.\n- Use browser DevTools to inspect elements, check network requests, or debug layout issues.\n\n<Warning>\nThe preview runs *in the workspace only*. It is **not** your published application. See [Preview vs Published](/preview-vs-deployed-separate) for the key differences.\n</Warning>\n\n---\n\n## Secrets and environment variables\n\nThe **Secrets / Env area** is where you configure API keys, connection strings, and any other environment variables your app needs.\n\n**Important distinctions:**\n\n- Secrets stored here apply to the **preview** environment. After the first publish, preview and production environment variables are separate; changes made here do not automatically apply to future published versions.\n- They are encrypted at rest and never exposed in the chat or logs.\n- The platform injects a special [Universal LLM Key](/the-universal-llm-key) automatically, so you can call OpenAI, Anthropic, and other LLM providers without adding your own keys during development.\n\n<Tip>\nAdd secrets *before* asking the agent to integrate third-party services. The agent will reference them by name (e.g., `STRIPE_SECRET_KEY`) when generating code.\n</Tip>\n\nLearn more in [Secrets & env variables](/secrets-env-variables).\n\n---\n\n## GitHub controls\n\nThe **GitHub controls** let you save your workspace code to a repository.\n\n**Core actions:**\n\n- **Save to GitHub:** Commit the current state of your workspace to a new or existing repository. This creates a snapshot you can share, review, or roll back to.\n\n<Warning>\nImporting a repo is only possible when starting a new job. There is no pull or in-platform merge available mid-project. See [Save to GitHub](/save-to-github).\n</Warning>\n\nFor step-by-step instructions, see [Save to GitHub](/save-to-github).\n\n---\n\n## Publish controls\n\nThe **Publish controls** are where you ship your application to a live, publicly accessible URL.\n\n**Available actions:**\n\n- **Publish:** Create a new published app from the current workspace state. You'll receive a unique URL that stays live until you delete it.\n- **Re-publish:** Push the latest workspace changes to an *existing* published app, preserving the same URL and published app ID.\n- **Replace:** Swap out the code of a running published app with a different workspace or branch, keeping the same domain and environment.\n\n<Info>\nPublished versions are *separate* from the preview. Each published app gets its own secrets, database, and runtime. [Preview vs Published](/preview-vs-deployed-separate) explains the isolation model.\n</Info>\n\nReview your options in [Publishing types](/deployment-types) and [Publishing plan levels](/deployment-plan-levels).\n\n---\n\n## Uploading files and images\n\nYou can **attach files directly** in the chat panel to guide the agent's work. Common use cases include:\n\n- **Design mockups:** Upload a screenshot or Figma export; the agent will replicate the layout and styling.\n- **Data samples:** Attach a CSV or JSON file; the agent will infer the schema and build import/export flows.\n- **Icons and logos:** Provide brand assets; the agent will reference them in the UI.\n- **Documents:** Share a spec, API response example, or requirements doc; the agent will parse it and apply the details.\n\n**How it works:**\n\n1. Click the attachment icon in the chat input (or drag and drop).\n2. Select one or more files (images, PDFs, spreadsheets, text).\n3. Send your message; the agent processes the files alongside your instructions.\n\n<Tip>\nCombine a screenshot with a short caption like \"Build a dashboard that looks like this\" for fast, accurate results.\n</Tip>\n\nFiles uploaded to the chat are stored temporarily for the agent's use. If your *application* needs persistent file storage (e.g., user uploads), see [File storage (Emergent Object Store)](/file-storage-emergent-object-store).\n","published_title":"A tour of the workspace","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"373f4f92-be45-4a80-9f2b-1384c87cd275","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"What is a Job?","slug":"what-is-a-job","content":"## What is a Job?\n\nIn Emergent, a **job** is a single application or project. Every time you describe a new app and start building, you create a job. The term \"job\" appears throughout the platform - in your workspace, notifications, and billing - and always refers to one discrete build.\n\nA job encompasses everything related to that app: the chat history where you described it, the generated code, test runs, published versions, and all iterations as you refine the product.\n\n<AccordionGroup>\n <Accordion title=\"Does one job = one app?\">\n Yes. Each job corresponds to exactly one application. If you want to build a weather dashboard and a recipe tracker, those are two separate jobs.\n\n Everything tied to a single app - code, dependencies, publish config, chat context - lives within that job's workspace.\n </Accordion>\n\n <Accordion title=\"How do I manage multiple jobs?\">\n Your workspace lists all your jobs in the sidebar. Click any job name to switch to it and load its chat, code, and publish history.\n\n You can rename, archive, or delete jobs from the job settings menu (accessed via the three-dot icon next to the job name). Archiving a job removes it from the active list but preserves all its data.\n </Accordion>\n\n <Accordion title=\"Can I work on multiple jobs at the same time?\">\n The workspace UI focuses on one job at a time, but you can open multiple browser tabs or windows - each pointing to a different job - and work in parallel.\n\n Builds, tests, and published versions run independently per job, so starting a build in one job does not block another.\n </Accordion>\n\n <Accordion title=\"What happens when I fork a job?\">\n Forking creates a new job that starts with a copy of the current job's code and state. This is useful when you want to explore a different direction or experiment without affecting the original.\n\n The forked job is fully independent: changes in one do not affect the other. For more detail, see [Forking](/forking).\n </Accordion>\n\n <Accordion title=\"Do jobs cost credits individually?\">\n Yes. Each job consumes credits based on its own build, test, and published app activity. Building and iterating on multiple jobs in parallel will use credits from your account balance accordingly.\n\n For pricing details, see [Managing credit usage](/managing-credit-usage).\n </Accordion>\n</AccordionGroup>\n\n---\n\n## Projects\n\n<Info>\n**Projects** let you group related jobs together for easier organisation. A project is simply a folder that contains multiple jobs - think of it as a way to keep all the apps for a client, a product suite, or a learning experiment in one place.\n</Info>\n\nTo create a project, use the \"Create New Project\" option in the project title card on the homepage or from the Profile icon menu by clicking the double arrow button on the current project name. You can then move existing jobs into it or create new jobs directly inside the project.\n\nSwitching between projects updates the job list to show only the jobs within that project. \n\nProjects are purely organisational - they do not share code, dependencies, or configuration between jobs. Each job inside a project remains independent.","order":8,"parent_id":null,"icon":"folder","description":"1. What a Job is: a single build/app/project in Emergent - the term you'll see across the platform.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T09:28:58.717694+00:00","published_at":"2026-09-25T09:28:58.717694+00:00","published_content":"## What is a Job?\n\nIn Emergent, a **job** is a single application or project. Every time you describe a new app and start building, you create a job. The term \"job\" appears throughout the platform - in your workspace, notifications, and billing - and always refers to one discrete build.\n\nA job encompasses everything related to that app: the chat history where you described it, the generated code, test runs, published versions, and all iterations as you refine the product.\n\n<AccordionGroup>\n <Accordion title=\"Does one job = one app?\">\n Yes. Each job corresponds to exactly one application. If you want to build a weather dashboard and a recipe tracker, those are two separate jobs.\n\n Everything tied to a single app - code, dependencies, publish config, chat context - lives within that job's workspace.\n </Accordion>\n\n <Accordion title=\"How do I manage multiple jobs?\">\n Your workspace lists all your jobs in the sidebar. Click any job name to switch to it and load its chat, code, and publish history.\n\n You can rename, archive, or delete jobs from the job settings menu (accessed via the three-dot icon next to the job name). Archiving a job removes it from the active list but preserves all its data.\n </Accordion>\n\n <Accordion title=\"Can I work on multiple jobs at the same time?\">\n The workspace UI focuses on one job at a time, but you can open multiple browser tabs or windows - each pointing to a different job - and work in parallel.\n\n Builds, tests, and published versions run independently per job, so starting a build in one job does not block another.\n </Accordion>\n\n <Accordion title=\"What happens when I fork a job?\">\n Forking creates a new job that starts with a copy of the current job's code and state. This is useful when you want to explore a different direction or experiment without affecting the original.\n\n The forked job is fully independent: changes in one do not affect the other. For more detail, see [Forking](/forking).\n </Accordion>\n\n <Accordion title=\"Do jobs cost credits individually?\">\n Yes. Each job consumes credits based on its own build, test, and published app activity. Building and iterating on multiple jobs in parallel will use credits from your account balance accordingly.\n\n For pricing details, see [Managing credit usage](/managing-credit-usage).\n </Accordion>\n</AccordionGroup>\n\n---\n\n## Projects\n\n<Info>\n**Projects** let you group related jobs together for easier organisation. A project is simply a folder that contains multiple jobs - think of it as a way to keep all the apps for a client, a product suite, or a learning experiment in one place.\n</Info>\n\nTo create a project, use the \"Create New Project\" option in the project title card on the homepage or from the Profile icon menu by clicking the double arrow button on the current project name. You can then move existing jobs into it or create new jobs directly inside the project.\n\nSwitching between projects updates the job list to show only the jobs within that project. \n\nProjects are purely organisational - they do not share code, dependencies, or configuration between jobs. Each job inside a project remains independent.","published_title":"What is a Job?","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"933fe24a-063b-43f1-86d9-7c212cbf21ba","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Team roles, permissions & collaboration","slug":"team-roles-permissions-collaboration","content":"## Understanding project roles\n\nEvery Emergent project has a **single owner** and can have any number of admins and members. Each role grants a different level of access to the project's resources, configuration and billing.\n\n<Note title=\"Personal projects\">\nIf you create a project on your own, you are the owner by default. Note that the default project cannot take invites; create a new project first before inviting collaborators.\n</Note>\n\n## Role capabilities\n\nThe table below shows what each role can do:\n\n| Capability | Owner | Admin | Member | Viewer |\n|------------|-------|-------|--------|--------|\n| **View & test the app** | ✓ | ✓ | ✓ | ✓ (Enterprise only) |\n| **Chat with the agent** | ✓ | ✓ | ✓ | - |\n| **Approve & publish changes** | ✓ | ✓ | ✓ | - |\n| **Edit project settings** | ✓ | ✓ | - | - |\n| **Invite or remove members** | ✓ | ✓ | - | - |\n| **Manage the database** | ✓ | ✓ | - | - |\n| **Configure custom domain** | ✓ | ✓ | - | - |\n| **View billing & usage** | ✓ | ✓ (view only) | - | - |\n| **Change plan or payment** | ✓ | - | - | - |\n| **Delete the project** | ✓ | - | - | - |\n\n<Callout type=\"info\" title=\"Viewer role is Enterprise-only\">\nThe Viewer role is available on Enterprise plans only. Viewers are ideal for stakeholders, clients or QA testers who need to see the live app and its history but should not make changes.\n</Callout>\n\n## Shared credit pool\n\nAll projects draw from a **shared credit pool** that belongs to the owner's account. Every collaborator - regardless of role - uses credits from that pool when they interact with the agent or publish changes.\n\n- The owner's [credit balance](/managing-credit-usage) funds all project activity.\n- Team members do not need their own credits or subscriptions.\n- Usage by any team member is attributed to the owner's account for billing purposes.\n\n<Warning title=\"Monitor usage in multi-user projects\">\nBecause all team members share the same credit pool, it's important to track usage if you have a large team or are working on multiple projects simultaneously.\n</Warning>\n\n## Inviting team members\n\n<Steps>\n<Step title=\"Open project settings\">\nNavigate to your project and click the **Profile** icon in the top navigation bar or the Project title card on the homepage.\n</Step>\n\n<Step title=\"Go to the Members tab\">\nSelect **Members** from the settings menu to see the current list of collaborators.\n</Step>\n\n<Step title=\"Send an invite\">\nEnter the email address of the person you want to invite, choose their role from the dropdown (**Admin** or **Member**), then click **Invite**.\n\nThey will receive an email with a link to accept the invitation and join the project.\n</Step>\n</Steps>\n\n<Tip title=\"Invite by email only\">\nInvitations are sent to email addresses. The recipient must have (or create) an Emergent account with that email to accept the invite.\n</Tip>\n\n## Changing a member's role\n\nOwners and admins can update any team member's role at any time:\n\n1. Open **Settings → Members**.\n2. Locate the member in the list.\n3. Click the role dropdown next to their name and select the new role.\n4. The change takes effect immediately - no email confirmation required.\n\n<Note>\nYou cannot change your own role if you are the owner.\n</Note>\n\n## Removing a team member\n\nOwners and admins can remove any member (including other admins) from the project:\n\n1. Open **Settings → Members**.\n2. Click the **Remove** button next to the member's name.\n3. Confirm the action in the dialog.\n\nRemoved members immediately lose access to the project, including the chat history, codebase and published app configuration. They can be re-invited later if needed.\n\n<Warning title=\"Removing an admin\">\nAdmins can remove other admins. If you have multiple admins, coordinate role changes carefully to avoid accidental lockouts.\n</Warning>\n\n## Transferring ownership\n\nProject ownership cannot be transferred (stays with the creating account).\n\n<Note>\nIf you need to change who manages billing and project control, please contact support at support@emergent.sh.\n</Note>\n\n## Best practices for team collaboration\n\n- **Assign roles conservatively**: Grant the minimum permissions needed for each team member's responsibilities.\n- **Use viewers for external stakeholders** (Enterprise only): Clients, investors or non-technical collaborators can see progress without risking accidental changes.\n- **Monitor the credit pool**: Keep an eye on usage if your team is large or actively iterating - credits are shared across all collaborators.\n\nFor more on how credits work and recharge policies, see [Managing credit usage](/managing-credit-usage).","order":9,"parent_id":null,"icon":"users","description":"Four project roles (Owner/Admin/Member/Viewer) with a capability matrix, a shared credit pool, inviting members, changing roles, and transferring ownership.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T09:24:02.923357+00:00","published_at":"2026-09-25T09:24:02.923357+00:00","published_content":"## Understanding project roles\n\nEvery Emergent project has a **single owner** and can have any number of admins and members. Each role grants a different level of access to the project's resources, configuration and billing.\n\n<Note title=\"Personal projects\">\nIf you create a project on your own, you are the owner by default. Note that the default project cannot take invites; create a new project first before inviting collaborators.\n</Note>\n\n## Role capabilities\n\nThe table below shows what each role can do:\n\n| Capability | Owner | Admin | Member | Viewer |\n|------------|-------|-------|--------|--------|\n| **View & test the app** | ✓ | ✓ | ✓ | ✓ (Enterprise only) |\n| **Chat with the agent** | ✓ | ✓ | ✓ | - |\n| **Approve & publish changes** | ✓ | ✓ | ✓ | - |\n| **Edit project settings** | ✓ | ✓ | - | - |\n| **Invite or remove members** | ✓ | ✓ | - | - |\n| **Manage the database** | ✓ | ✓ | - | - |\n| **Configure custom domain** | ✓ | ✓ | - | - |\n| **View billing & usage** | ✓ | ✓ (view only) | - | - |\n| **Change plan or payment** | ✓ | - | - | - |\n| **Delete the project** | ✓ | - | - | - |\n\n<Callout type=\"info\" title=\"Viewer role is Enterprise-only\">\nThe Viewer role is available on Enterprise plans only. Viewers are ideal for stakeholders, clients or QA testers who need to see the live app and its history but should not make changes.\n</Callout>\n\n## Shared credit pool\n\nAll projects draw from a **shared credit pool** that belongs to the owner's account. Every collaborator - regardless of role - uses credits from that pool when they interact with the agent or publish changes.\n\n- The owner's [credit balance](/managing-credit-usage) funds all project activity.\n- Team members do not need their own credits or subscriptions.\n- Usage by any team member is attributed to the owner's account for billing purposes.\n\n<Warning title=\"Monitor usage in multi-user projects\">\nBecause all team members share the same credit pool, it's important to track usage if you have a large team or are working on multiple projects simultaneously.\n</Warning>\n\n## Inviting team members\n\n<Steps>\n<Step title=\"Open project settings\">\nNavigate to your project and click the **Profile** icon in the top navigation bar or the Project title card on the homepage.\n</Step>\n\n<Step title=\"Go to the Members tab\">\nSelect **Members** from the settings menu to see the current list of collaborators.\n</Step>\n\n<Step title=\"Send an invite\">\nEnter the email address of the person you want to invite, choose their role from the dropdown (**Admin** or **Member**), then click **Invite**.\n\nThey will receive an email with a link to accept the invitation and join the project.\n</Step>\n</Steps>\n\n<Tip title=\"Invite by email only\">\nInvitations are sent to email addresses. The recipient must have (or create) an Emergent account with that email to accept the invite.\n</Tip>\n\n## Changing a member's role\n\nOwners and admins can update any team member's role at any time:\n\n1. Open **Settings → Members**.\n2. Locate the member in the list.\n3. Click the role dropdown next to their name and select the new role.\n4. The change takes effect immediately - no email confirmation required.\n\n<Note>\nYou cannot change your own role if you are the owner.\n</Note>\n\n## Removing a team member\n\nOwners and admins can remove any member (including other admins) from the project:\n\n1. Open **Settings → Members**.\n2. Click the **Remove** button next to the member's name.\n3. Confirm the action in the dialog.\n\nRemoved members immediately lose access to the project, including the chat history, codebase and published app configuration. They can be re-invited later if needed.\n\n<Warning title=\"Removing an admin\">\nAdmins can remove other admins. If you have multiple admins, coordinate role changes carefully to avoid accidental lockouts.\n</Warning>\n\n## Transferring ownership\n\nProject ownership cannot be transferred (stays with the creating account).\n\n<Note>\nIf you need to change who manages billing and project control, please contact support at support@emergent.sh.\n</Note>\n\n## Best practices for team collaboration\n\n- **Assign roles conservatively**: Grant the minimum permissions needed for each team member's responsibilities.\n- **Use viewers for external stakeholders** (Enterprise only): Clients, investors or non-technical collaborators can see progress without risking accidental changes.\n- **Monitor the credit pool**: Keep an eye on usage if your team is large or actively iterating - credits are shared across all collaborators.\n\nFor more on how credits work and recharge policies, see [Managing credit usage](/managing-credit-usage).","published_title":"Team roles, permissions & collaboration","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"8b4de37e-36af-4d9a-9ee1-51fb4a68cd34","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Understanding models (E1/E2/E3 & Maxx)","slug":"understanding-models-e1-e2-e3-maxx","content":"## What E1, E2, and E3 are\n\nEmergent gives you three **agents**, E-1, E-2, and E-3, each running a different workflow. The LLM powering those agents is a **separate** selector. Think of the agent choice as picking *how* work gets done, not just how hard the model thinks.\n\n- **E-1**: The default agent. Executes a clear step-by-step build workflow. Best for everyday features, bug fixes, and iterative changes.\n- **E-2**: An integration-proving agent. Goes further to validate that the pieces it builds actually fit together, making it well-suited for moderate-complexity work involving multiple services or components.\n- **E-3**: The autonomous agent. Runs E-1 as a sub-agent under its own orchestration loop, handling ambitious, open-ended goals with minimal hand-holding.\n\n<Tip title=\"Start with E-1 or E-2\">\nE-1 covers most everyday tasks efficiently. Reach for E-2 when you need integration confidence, and reserve E-3 for genuinely large or ambiguous goals.\n</Tip>\n\n### When to use which agent\n\n| Agent | Workflow style | Best for |\n|-------|---------------|----------|\n| **E-1** | Step-by-step builder | Quick fixes, new components, standard integrations |\n| **E-2** | Integration-proving | Multi-service features, moderate refactors, reliability-sensitive changes |\n| **E-3** | Autonomous (runs E-1 as sub-agent) | Large architectural goals, open-ended projects, complex multi-step builds |\n\nYou select the agent **before submitting your first message** in the job creation form. The model you want to use is chosen separately via the model selector.\n\n<Warning title=\"Agents cannot be switched mid-conversation\">\nOnce a job has started, the agent is fixed for that conversation. Even forking the conversation keeps the same agent. If you want a different agent, start a new job.\n</Warning>\n\n---\n\n## Maxx mode\n\n**Maxx mode is a deeper-reasoning toggle** available in the prompt interface. When enabled, the agent applies more thorough reasoning to your request, useful when a problem genuinely warrants it.\n\nEnabling Maxx consumes **significantly more credits** than a standard run. There is no published credit multiplier.\n\n<Warning title=\"Maxx is a Pro-only feature\">\nMaxx mode is available exclusively on the **Pro plan**. It is not accessible on Free or Standard plans.\n</Warning>\n\n### When to enable Maxx\n\n<Steps>\n<Step title=\"Identify the need\">\nAsk yourself: *Is the agent's default reasoning clearly insufficient for this problem?* Maxx is most valuable for subtle, high-stakes logic where deeper thinking produces meaningfully better results.\n</Step>\n\n<Step title=\"Enable before submitting\">\nToggle Maxx mode in the prompt interface before you start the job. It applies to that job's reasoning depth.\n</Step>\n\n<Step title=\"Monitor credit usage\">\nCheck your [credit balance](/managing-credit-usage) after the job completes. Because Maxx consumes significantly more credits, consider breaking very large prompts into smaller sequential jobs if cost is a concern.\n</Step>\n</Steps>\n\n---\n\n## Choosing the right combination\n\nA quick decision guide:\n\n- **Small, obvious change?** → E-1, Maxx off.\n- **Standard feature or multi-service integration?** → E-2, Maxx off.\n- **Large, open-ended, or highly autonomous goal?** → E-3, Maxx off (add Maxx only if you're on Pro and the reasoning depth matters).\n- **On Pro and hitting a genuinely hard reasoning problem?** → Enable Maxx on whichever agent fits the workflow.\n\nRemember: if a job doesn't produce what you need, start a new job with a refined prompt or a different agent, you cannot switch agents within an existing conversation.\n\n<Tip title=\"Iterate cheaply first\">\nStart with E-1 or E-2 and Maxx off. A tighter follow-up in the same conversation, or a fresh job with a more specific prompt, is often more credit-efficient than jumping straight to E-3 + Maxx.\n</Tip>","order":11,"parent_id":null,"icon":"brain","description":"Understanding models (E1/E2/E3 & Maxx)","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:00.765199+00:00","published_at":"2026-09-22T06:20:00.765199+00:00","published_content":"## What E1, E2, and E3 are\n\nEmergent gives you three **agents**, E-1, E-2, and E-3, each running a different workflow. The LLM powering those agents is a **separate** selector. Think of the agent choice as picking *how* work gets done, not just how hard the model thinks.\n\n- **E-1**: The default agent. Executes a clear step-by-step build workflow. Best for everyday features, bug fixes, and iterative changes.\n- **E-2**: An integration-proving agent. Goes further to validate that the pieces it builds actually fit together, making it well-suited for moderate-complexity work involving multiple services or components.\n- **E-3**: The autonomous agent. Runs E-1 as a sub-agent under its own orchestration loop, handling ambitious, open-ended goals with minimal hand-holding.\n\n<Tip title=\"Start with E-1 or E-2\">\nE-1 covers most everyday tasks efficiently. Reach for E-2 when you need integration confidence, and reserve E-3 for genuinely large or ambiguous goals.\n</Tip>\n\n### When to use which agent\n\n| Agent | Workflow style | Best for |\n|-------|---------------|----------|\n| **E-1** | Step-by-step builder | Quick fixes, new components, standard integrations |\n| **E-2** | Integration-proving | Multi-service features, moderate refactors, reliability-sensitive changes |\n| **E-3** | Autonomous (runs E-1 as sub-agent) | Large architectural goals, open-ended projects, complex multi-step builds |\n\nYou select the agent **before submitting your first message** in the job creation form. The model you want to use is chosen separately via the model selector.\n\n<Warning title=\"Agents cannot be switched mid-conversation\">\nOnce a job has started, the agent is fixed for that conversation. Even forking the conversation keeps the same agent. If you want a different agent, start a new job.\n</Warning>\n\n---\n\n## Maxx mode\n\n**Maxx mode is a deeper-reasoning toggle** available in the prompt interface. When enabled, the agent applies more thorough reasoning to your request, useful when a problem genuinely warrants it.\n\nEnabling Maxx consumes **significantly more credits** than a standard run. There is no published credit multiplier.\n\n<Warning title=\"Maxx is a Pro-only feature\">\nMaxx mode is available exclusively on the **Pro plan**. It is not accessible on Free or Standard plans.\n</Warning>\n\n### When to enable Maxx\n\n<Steps>\n<Step title=\"Identify the need\">\nAsk yourself: *Is the agent's default reasoning clearly insufficient for this problem?* Maxx is most valuable for subtle, high-stakes logic where deeper thinking produces meaningfully better results.\n</Step>\n\n<Step title=\"Enable before submitting\">\nToggle Maxx mode in the prompt interface before you start the job. It applies to that job's reasoning depth.\n</Step>\n\n<Step title=\"Monitor credit usage\">\nCheck your [credit balance](/managing-credit-usage) after the job completes. Because Maxx consumes significantly more credits, consider breaking very large prompts into smaller sequential jobs if cost is a concern.\n</Step>\n</Steps>\n\n---\n\n## Choosing the right combination\n\nA quick decision guide:\n\n- **Small, obvious change?** → E-1, Maxx off.\n- **Standard feature or multi-service integration?** → E-2, Maxx off.\n- **Large, open-ended, or highly autonomous goal?** → E-3, Maxx off (add Maxx only if you're on Pro and the reasoning depth matters).\n- **On Pro and hitting a genuinely hard reasoning problem?** → Enable Maxx on whichever agent fits the workflow.\n\nRemember: if a job doesn't produce what you need, start a new job with a refined prompt or a different agent, you cannot switch agents within an existing conversation.\n\n<Tip title=\"Iterate cheaply first\">\nStart with E-1 or E-2 and Maxx off. A tighter follow-up in the same conversation, or a fresh job with a more specific prompt, is often more credit-efficient than jumping straight to E-3 + Maxx.\n</Tip>","published_title":"Understanding models (E1/E2/E3 & Maxx)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"8d64cb95-c424-4168-8910-aaca821f27f4","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Previewing & iterating","slug":"previewing-iterating","content":"> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Using the preview\n\nFor guidance on refining and iterating on your app, see [Make it yours](/make-it-yours).\n\nAs the AI agent builds your app, Emergent automatically generates a **live preview**. This preview updates in real time as the agent writes code, installs dependencies, and configures features - no manual refresh required in most cases.\n\nThe preview runs in a sandboxed environment separate from your eventual production published app. It's designed for rapid iteration: you can test each feature, explore the UI, and verify behavior before you ever commit to publishing.\n\n### Sharing the preview\n\nYou can share the preview URL with teammates or stakeholders to gather feedback before publishing. Keep in mind that the preview environment may reset or become unavailable if the workspace is idle for an extended period, so it's not suitable for long-term public access.\n\n<Warning title=\"Preview is NOT your published app\">\nThe preview environment and your published app are **completely separate**. Changes you see in the preview do *not* automatically appear in production.\n\n- The preview uses temporary infrastructure that spins up and down as you build.\n- Published app is a deliberate step that provisions persistent infrastructure, locks in a specific version of your code, and assigns a production domain.\n\nUntil you explicitly publish (or re-publish), your live app will continue running the last published version - even if the preview shows something totally different. For details on how these environments differ, see [Preview vs Published](/preview-vs-deployed-separate).\n</Warning>\n\n## When you're ready to publish\n\nOnce you're satisfied with what you see in the preview, you can move to published app. Published app packages your app, provisions infrastructure according to your [Publishing plan level](/deployment-plan-levels), and publishes it at a stable URL.\n\nCheck the [Publishing types](/deployment-types) page to understand your options, and see [A tour of the workspace](/a-tour-of-the-workspace) for the publish button location and workflow.\n","order":12,"parent_id":null,"icon":"eye","description":"Previewing & iterating","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:01.003873+00:00","published_at":"2026-09-22T06:20:01.003873+00:00","published_content":"> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Using the preview\n\nFor guidance on refining and iterating on your app, see [Make it yours](/make-it-yours).\n\nAs the AI agent builds your app, Emergent automatically generates a **live preview**. This preview updates in real time as the agent writes code, installs dependencies, and configures features - no manual refresh required in most cases.\n\nThe preview runs in a sandboxed environment separate from your eventual production published app. It's designed for rapid iteration: you can test each feature, explore the UI, and verify behavior before you ever commit to publishing.\n\n### Sharing the preview\n\nYou can share the preview URL with teammates or stakeholders to gather feedback before publishing. Keep in mind that the preview environment may reset or become unavailable if the workspace is idle for an extended period, so it's not suitable for long-term public access.\n\n<Warning title=\"Preview is NOT your published app\">\nThe preview environment and your published app are **completely separate**. Changes you see in the preview do *not* automatically appear in production.\n\n- The preview uses temporary infrastructure that spins up and down as you build.\n- Published app is a deliberate step that provisions persistent infrastructure, locks in a specific version of your code, and assigns a production domain.\n\nUntil you explicitly publish (or re-publish), your live app will continue running the last published version - even if the preview shows something totally different. For details on how these environments differ, see [Preview vs Published](/preview-vs-deployed-separate).\n</Warning>\n\n## When you're ready to publish\n\nOnce you're satisfied with what you see in the preview, you can move to published app. Published app packages your app, provisions infrastructure according to your [Publishing plan level](/deployment-plan-levels), and publishes it at a stable URL.\n\nCheck the [Publishing types](/deployment-types) page to understand your options, and see [A tour of the workspace](/a-tour-of-the-workspace) for the publish button location and workflow.\n","published_title":"Previewing & iterating","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"227f531a-da4b-43cc-b0b1-f399874a5677","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Debugging & testing with the agent","slug":"debugging-testing-with-the-agent","content":"> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Overview\n\nNewer to this? Start with [Try it before you share it](/try-it-before-you-share-it) and [When something breaks](/when-something-breaks); this page covers the deeper testing layer.\n\nWhen your app doesn't behave as expected, Emergent's agent can diagnose and fix issues directly in the chat. This guide shows you how to surface errors, provide context, and use the platform's built-in testing tools to ship a polished app.\n\n<Note>\nThe agent works best when given complete error messages and clear reproduction steps. The more detail you provide, the faster it can iterate toward a fix.\n</Note>\n\n## Debugging with the agent\n\n<Steps>\n<Step title=\"Paste the full error message\">\nWhen your app throws an error, copy the **entire error text** from the console, logs, or error modal - including stack traces, file paths, and line numbers. Paste it directly into the chat with a short prompt:\n\n```\nplease solve this error\n\n[full error text here]\n```\n\nThe agent will parse the stack trace, identify the failing component or API call, and propose a fix.\n\n<Tip>\nIf the error occurs in the browser console, right-click the message and select \"Copy\" to capture the full output, including stack frames.\n</Tip>\n</Step>\n\n<Step title=\"Upload a screenshot for UI bugs\">\nVisual issues - misaligned components, missing styles, incorrect colors - are often faster to diagnose from a screenshot. Upload an image (drag-and-drop or click the attachment icon) and add a brief description:\n\n```\nThis modal is cut off on mobile (screenshot attached). The submit button is hidden below the fold.\n```\n\nThe agent will inspect the component's layout constraints and suggest CSS or flex adjustments.\n</Step>\n\n<Step title=\"Provide context for stubborn bugs\">\nIf a bug is intermittent or hard to reproduce, describe the conditions:\n\n- **When** does it happen? (e.g., \"only after logging in,\" \"on the second page load\")\n- **Where** does it occur? (specific page, route, or user flow)\n- **What** user action triggers it? (button click, form submission, navigation)\n\nExample:\n\n```\nThe \"Add to Cart\" button doesn't respond when I click it after navigating from the product list. It works fine if I reload the product detail page directly.\n```\n\nThis helps the agent narrow down state-management issues, routing bugs, or missing event handlers.\n</Step>\n\n<Step title=\"Read automated test results\">\nThe agent has testing capabilities and can run tests covering routes, API endpoints, and key user flows. If you request testing or the agent surfaces test output, it will:\n\n1. Show which test failed and why\n2. Automatically attempt a fix\n3. Re-run the tests to confirm the issue is resolved\n\nYou can also request specific tests:\n\n```\ntest the checkout flow end-to-end\n```\n\n<Info>\nAutomated tests catch regressions early - especially useful when you're iterating quickly on features. Review the test output to understand what the agent validated.\n</Info>\n</Step>\n\n<Step title=\"Request internal test builds for mobile apps\">\nBefore publishing to the App Store or Play Store, generate an **internal test build** to validate the experience on real devices. In the chat, ask:\n\n```\ncreate an iOS test build\n```\n\nor\n\n```\ncreate an Android test build\n```\n\nThe agent will produce a signed build (TestFlight for iOS; APK/AAB direct install for Android, note that native builds require a paid Emergent plan) and provide installation instructions. Share the build link with testers to gather feedback before your public launch.\n\n<Tip>\nInternal builds let you test on actual hardware, verify push notifications, and confirm in-app purchases - scenarios that are difficult to simulate in the workspace preview.\n</Tip>\n\nSee [Publishing to the stores](/publishing-to-the-stores) for details on moving from test builds to production releases.\n</Step>\n</Steps>\n\n## When to escalate\n\nMost bugs can be resolved in chat with clear error messages and context. If an issue persists after several iterations:\n\n- Check the [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) troubleshooting guide for performance-related problems\n- Verify that third-party API keys and environment variables are correctly configured (see [The Universal LLM Key](/the-universal-llm-key) for examples)\n- Review the [Glossary of Emergent terms](/glossary-of-emergent-terms) to ensure you're using platform concepts correctly\n\n<Warning>\nIf your app handles sensitive data, review [Your data & ownership](/your-data-ownership) to understand how logs and error traces are stored during debugging sessions.\n</Warning>\n","order":13,"parent_id":null,"icon":"bug","description":"1. Paste the full error: copy complete text; 'please solve this error'.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:00.769668+00:00","published_at":"2026-09-22T06:20:00.769668+00:00","published_content":"> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Overview\n\nNewer to this? Start with [Try it before you share it](/try-it-before-you-share-it) and [When something breaks](/when-something-breaks); this page covers the deeper testing layer.\n\nWhen your app doesn't behave as expected, Emergent's agent can diagnose and fix issues directly in the chat. This guide shows you how to surface errors, provide context, and use the platform's built-in testing tools to ship a polished app.\n\n<Note>\nThe agent works best when given complete error messages and clear reproduction steps. The more detail you provide, the faster it can iterate toward a fix.\n</Note>\n\n## Debugging with the agent\n\n<Steps>\n<Step title=\"Paste the full error message\">\nWhen your app throws an error, copy the **entire error text** from the console, logs, or error modal - including stack traces, file paths, and line numbers. Paste it directly into the chat with a short prompt:\n\n```\nplease solve this error\n\n[full error text here]\n```\n\nThe agent will parse the stack trace, identify the failing component or API call, and propose a fix.\n\n<Tip>\nIf the error occurs in the browser console, right-click the message and select \"Copy\" to capture the full output, including stack frames.\n</Tip>\n</Step>\n\n<Step title=\"Upload a screenshot for UI bugs\">\nVisual issues - misaligned components, missing styles, incorrect colors - are often faster to diagnose from a screenshot. Upload an image (drag-and-drop or click the attachment icon) and add a brief description:\n\n```\nThis modal is cut off on mobile (screenshot attached). The submit button is hidden below the fold.\n```\n\nThe agent will inspect the component's layout constraints and suggest CSS or flex adjustments.\n</Step>\n\n<Step title=\"Provide context for stubborn bugs\">\nIf a bug is intermittent or hard to reproduce, describe the conditions:\n\n- **When** does it happen? (e.g., \"only after logging in,\" \"on the second page load\")\n- **Where** does it occur? (specific page, route, or user flow)\n- **What** user action triggers it? (button click, form submission, navigation)\n\nExample:\n\n```\nThe \"Add to Cart\" button doesn't respond when I click it after navigating from the product list. It works fine if I reload the product detail page directly.\n```\n\nThis helps the agent narrow down state-management issues, routing bugs, or missing event handlers.\n</Step>\n\n<Step title=\"Read automated test results\">\nThe agent has testing capabilities and can run tests covering routes, API endpoints, and key user flows. If you request testing or the agent surfaces test output, it will:\n\n1. Show which test failed and why\n2. Automatically attempt a fix\n3. Re-run the tests to confirm the issue is resolved\n\nYou can also request specific tests:\n\n```\ntest the checkout flow end-to-end\n```\n\n<Info>\nAutomated tests catch regressions early - especially useful when you're iterating quickly on features. Review the test output to understand what the agent validated.\n</Info>\n</Step>\n\n<Step title=\"Request internal test builds for mobile apps\">\nBefore publishing to the App Store or Play Store, generate an **internal test build** to validate the experience on real devices. In the chat, ask:\n\n```\ncreate an iOS test build\n```\n\nor\n\n```\ncreate an Android test build\n```\n\nThe agent will produce a signed build (TestFlight for iOS; APK/AAB direct install for Android, note that native builds require a paid Emergent plan) and provide installation instructions. Share the build link with testers to gather feedback before your public launch.\n\n<Tip>\nInternal builds let you test on actual hardware, verify push notifications, and confirm in-app purchases - scenarios that are difficult to simulate in the workspace preview.\n</Tip>\n\nSee [Publishing to the stores](/publishing-to-the-stores) for details on moving from test builds to production releases.\n</Step>\n</Steps>\n\n## When to escalate\n\nMost bugs can be resolved in chat with clear error messages and context. If an issue persists after several iterations:\n\n- Check the [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) troubleshooting guide for performance-related problems\n- Verify that third-party API keys and environment variables are correctly configured (see [The Universal LLM Key](/the-universal-llm-key) for examples)\n- Review the [Glossary of Emergent terms](/glossary-of-emergent-terms) to ensure you're using platform concepts correctly\n\n<Warning>\nIf your app handles sensitive data, review [Your data & ownership](/your-data-ownership) to understand how logs and error traces are stored during debugging sessions.\n</Warning>\n","published_title":"Debugging & testing with the agent","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"b27fe55b-bc45-4a7f-a7e4-7a3874e601bd","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Building from your phone","slug":"building-from-the-emergent-mobile-app","content":"## Overview\n\nThe Emergent mobile experience lets you build, preview and manage your projects from your phone or tablet, no native app download required. Mobile access is through the **web/PWA at [app.emergent.sh](https://app.emergent.sh)**. The Emergent native app is not currently distributed on the App Store or Google Play (existing installs continue to work, but no new downloads are available).\n\nYou can chat with agents, watch builds in real time, test previews and start new apps, all from your mobile browser.\n\n---\n\n## What you can do\n\n<CardGroup cols={2}>\n  <Card title=\"Chat & build\" icon=\"message-square\">\n    Describe features, review agent changes and approve builds in the conversation thread.\n  </Card>\n  <Card title=\"In-app preview\" icon=\"smartphone\">\n    See your Expo/React Native app running in an embedded preview, no separate browser tab needed.\n  </Card>\n  <Card title=\"Start new apps\" icon=\"plus-circle\">\n    Begin a brand-new app from the Home tab. (Brainstorm jobs and Projects management are not available on mobile.)\n  </Card>\n  <Card title=\"Manage your account\" icon=\"user\">\n    View subscription details, credits and settings from the Account tab.\n  </Card>\n</CardGroup>\n\n---\n\n## Accessing Emergent on mobile\n\nVisit **[app.emergent.sh](https://app.emergent.sh)** in any mobile browser. For the best experience, add it to your home screen as a PWA:\n\n- **iOS (Safari):** tap the Share icon → **Add to Home Screen**\n- **Android (Chrome):** tap the menu (three dots) → **Add to Home Screen**\n\n<Note>\nThe Emergent native app is **not available for download** on the App Store or Google Play. New installs must use the web/PWA at app.emergent.sh.\n</Note>\n\n---\n\n## Navigation tabs\n\nThe Emergent mobile web app has three bottom tabs:\n\n| Tab | What it does |\n|-----|--------------|\n| **My Apps** | Filterable list of all your apps, tap any to open it and start building. |\n| **Home** | Start a new app, access recent activity and workspace highlights. |\n| **Account** | Subscription, credits and sign-out. |\n\n---\n\n## Starting and building a project\n\n<Steps>\n  <Step title=\"Open My Apps or Home\">\n    Tap **My Apps** to open an existing project, or tap **Home** to start a new one.\n  </Step>\n  <Step title=\"Chat with the agent\">\n    The conversation thread appears. Describe the app or changes you want; the agent gets to work.\n  </Step>\n  <Step title=\"View the preview\">\n    When the agent finishes, the embedded preview updates automatically, no separate publish step needed for preview.\n  </Step>\n  <Step title=\"Iterate\">\n    Continue chatting to refine features; each build refreshes the embedded preview.\n  </Step>\n</Steps>\n\n---\n\n## In-app preview\n\nFor **Expo/React Native** projects, the preview is embedded directly in the mobile app. You can also scan an **Expo Go QR code** to open the project inside the Expo Go app on your device (for newer projects, device-code authentication is used instead of the camera QR flow).\n\n<Note>\nMobile app previews are Expo/React Native only. All mobile apps built on Emergent use the Expo/React Native stack.\n</Note>\n\nIf you need to test on a physical device, scan the Expo Go QR code shown in the preview panel. No same-Wi-Fi connection is required, Emergent's cloud-hosted device streaming is free and works anywhere.\n\n---\n\n## Over-the-air (OTA) updates\n\nOTA is how the **Emergent platform itself** delivers updates to the app, it is not a user-facing button or workflow. For your own published Expo apps:\n\n- **JavaScript and asset changes** can be shipped OTA by re-publishing your project (no store review required).\n- **Native binary changes** (new permissions, new SDKs) require a full rebuild and store submission triggered from the Publish panel.\n\nThere is no \"Push OTA Update\" button exposed to users in the mobile interface.\n\n---\n\n## What's available on mobile vs. web\n\n<Note>\nNew apps **can** be started from the Home tab on mobile. However, Projects management and Brainstorm jobs are not available on mobile, use the web workspace at app.emergent.sh for those workflows.\n</Note>\n\n| Feature | Mobile (app.emergent.sh) | Web workspace |\n|---------|--------------------------|---------------|\n| Start a new app (Home tab) | ✅ | ✅ |\n| Open and iterate existing apps | ✅ | ✅ |\n| Embedded in-app preview | ✅ | ✅ |\n| Fork / clone project | ✅ | ✅ |\n| Push to GitHub | ✅ | ✅ |\n| VS Code view | ✅ | ✅ |\n| Brainstorm job type | ❌ | ✅ |\n| Projects management | ❌ | ✅ |\n| Bulk environment management | ❌ | ✅ |\n\n---\n\n## Best practices\n\n<AccordionGroup>\n  <Accordion title=\"Use mobile for iteration, web for advanced workflows\">\n    Chat-based building and previewing works great on mobile. For GitHub sync, forking, VS Code access and Brainstorm jobs, switch to the web workspace at app.emergent.sh.\n  </Accordion>\n  <Accordion title=\"Test Expo apps on a real device\">\n    Scan the Expo Go QR code from the preview panel to run your app on your physical device. This is the fastest way to catch UI glitches and permission prompts before you publish.\n  </Accordion>\n  <Accordion title=\"Publish from the web for store builds\">\n    Native APK/AAB/IPA builds are triggered from the Publish panel on the web workspace. Fix issues in chat → re-publish → then rebuild from the panel.\n  </Accordion>\n</AccordionGroup>\n","order":14,"parent_id":null,"icon":"layers","description":"Build, preview and manage your apps from your phone via the Emergent mobile web app at app.emergent.sh - navigation tabs, in-app previews, OTA updates, deep linking, and the feature limits vs desktop.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:00.767047+00:00","published_at":"2026-09-22T06:20:00.767047+00:00","published_content":"## Overview\n\nThe Emergent mobile experience lets you build, preview and manage your projects from your phone or tablet, no native app download required. Mobile access is through the **web/PWA at [app.emergent.sh](https://app.emergent.sh)**. The Emergent native app is not currently distributed on the App Store or Google Play (existing installs continue to work, but no new downloads are available).\n\nYou can chat with agents, watch builds in real time, test previews and start new apps, all from your mobile browser.\n\n---\n\n## What you can do\n\n<CardGroup cols={2}>\n  <Card title=\"Chat & build\" icon=\"message-square\">\n    Describe features, review agent changes and approve builds in the conversation thread.\n  </Card>\n  <Card title=\"In-app preview\" icon=\"smartphone\">\n    See your Expo/React Native app running in an embedded preview, no separate browser tab needed.\n  </Card>\n  <Card title=\"Start new apps\" icon=\"plus-circle\">\n    Begin a brand-new app from the Home tab. (Brainstorm jobs and Projects management are not available on mobile.)\n  </Card>\n  <Card title=\"Manage your account\" icon=\"user\">\n    View subscription details, credits and settings from the Account tab.\n  </Card>\n</CardGroup>\n\n---\n\n## Accessing Emergent on mobile\n\nVisit **[app.emergent.sh](https://app.emergent.sh)** in any mobile browser. For the best experience, add it to your home screen as a PWA:\n\n- **iOS (Safari):** tap the Share icon → **Add to Home Screen**\n- **Android (Chrome):** tap the menu (three dots) → **Add to Home Screen**\n\n<Note>\nThe Emergent native app is **not available for download** on the App Store or Google Play. New installs must use the web/PWA at app.emergent.sh.\n</Note>\n\n---\n\n## Navigation tabs\n\nThe Emergent mobile web app has three bottom tabs:\n\n| Tab | What it does |\n|-----|--------------|\n| **My Apps** | Filterable list of all your apps, tap any to open it and start building. |\n| **Home** | Start a new app, access recent activity and workspace highlights. |\n| **Account** | Subscription, credits and sign-out. |\n\n---\n\n## Starting and building a project\n\n<Steps>\n  <Step title=\"Open My Apps or Home\">\n    Tap **My Apps** to open an existing project, or tap **Home** to start a new one.\n  </Step>\n  <Step title=\"Chat with the agent\">\n    The conversation thread appears. Describe the app or changes you want; the agent gets to work.\n  </Step>\n  <Step title=\"View the preview\">\n    When the agent finishes, the embedded preview updates automatically, no separate publish step needed for preview.\n  </Step>\n  <Step title=\"Iterate\">\n    Continue chatting to refine features; each build refreshes the embedded preview.\n  </Step>\n</Steps>\n\n---\n\n## In-app preview\n\nFor **Expo/React Native** projects, the preview is embedded directly in the mobile app. You can also scan an **Expo Go QR code** to open the project inside the Expo Go app on your device (for newer projects, device-code authentication is used instead of the camera QR flow).\n\n<Note>\nMobile app previews are Expo/React Native only. All mobile apps built on Emergent use the Expo/React Native stack.\n</Note>\n\nIf you need to test on a physical device, scan the Expo Go QR code shown in the preview panel. No same-Wi-Fi connection is required, Emergent's cloud-hosted device streaming is free and works anywhere.\n\n---\n\n## Over-the-air (OTA) updates\n\nOTA is how the **Emergent platform itself** delivers updates to the app, it is not a user-facing button or workflow. For your own published Expo apps:\n\n- **JavaScript and asset changes** can be shipped OTA by re-publishing your project (no store review required).\n- **Native binary changes** (new permissions, new SDKs) require a full rebuild and store submission triggered from the Publish panel.\n\nThere is no \"Push OTA Update\" button exposed to users in the mobile interface.\n\n---\n\n## What's available on mobile vs. web\n\n<Note>\nNew apps **can** be started from the Home tab on mobile. However, Projects management and Brainstorm jobs are not available on mobile, use the web workspace at app.emergent.sh for those workflows.\n</Note>\n\n| Feature | Mobile (app.emergent.sh) | Web workspace |\n|---------|--------------------------|---------------|\n| Start a new app (Home tab) | ✅ | ✅ |\n| Open and iterate existing apps | ✅ | ✅ |\n| Embedded in-app preview | ✅ | ✅ |\n| Fork / clone project | ✅ | ✅ |\n| Push to GitHub | ✅ | ✅ |\n| VS Code view | ✅ | ✅ |\n| Brainstorm job type | ❌ | ✅ |\n| Projects management | ❌ | ✅ |\n| Bulk environment management | ❌ | ✅ |\n\n---\n\n## Best practices\n\n<AccordionGroup>\n  <Accordion title=\"Use mobile for iteration, web for advanced workflows\">\n    Chat-based building and previewing works great on mobile. For GitHub sync, forking, VS Code access and Brainstorm jobs, switch to the web workspace at app.emergent.sh.\n  </Accordion>\n  <Accordion title=\"Test Expo apps on a real device\">\n    Scan the Expo Go QR code from the preview panel to run your app on your physical device. This is the fastest way to catch UI glitches and permission prompts before you publish.\n  </Accordion>\n  <Accordion title=\"Publish from the web for store builds\">\n    Native APK/AAB/IPA builds are triggered from the Publish panel on the web workspace. Fix issues in chat → re-publish → then rebuild from the panel.\n  </Accordion>\n</AccordionGroup>\n","published_title":"Building from your phone","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"f6142e02-71ec-43ce-9876-d7417c3522ce","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Forking","slug":"forking","content":"## What is Forking?\n\n**Forking** creates a complete, independent copy of your current app - including its entire codebase, database schema, and a summarized version of the chat history up to the fork point. The forked app runs as a separate project with its own build pipeline, database, and published app.\n\nUse forking when you want to:\n\n- Experiment with a major architectural change without risking your production app\n- Create a variant of an app for a different audience or use case\n- Preserve a stable snapshot before attempting risky refactors\n\n<Info>\nForking is different from [rollback](/checkpoints-undo-anything). Rollback rewinds your *current* app to an earlier state; forking creates a *new* app that diverges from the original.\n</Info>\n\n## How to Fork an App\n\n<Steps>\n<Step title=\"Open the Fork button\">\nIn the chat input bar (web only), click the **Fork** button to begin the forking process. This opens the Configure New Chat dialog.\n</Step>\n\n<Step title=\"Select Fork\">\nConfirm your fork settings in the Configure New Chat dialog. The platform will duplicate the app state - code and cloned volume (including data) - into a new project, with a summarized (editable) chat history.\n</Step>\n\n<Step title=\"Name the fork\">\nGive your fork a descriptive name (e.g., `MyApp - Experimental Redesign`) so you can distinguish it from the original.\n</Step>\n\n<Step title=\"Continue building\">\nThe forked app appears in your workspace as a standalone project. Chat, build, and publish independently. Changes to the fork do not affect the original app, and vice versa.\n</Step>\n</Steps>\n\n<Tip>\nFork *before* starting a risky change. If the experiment succeeds, you can continue with the fork; if it fails, simply delete the fork and return to the original.\n</Tip>\n\n## What Gets Copied\n\nWhen you fork an app, Emergent duplicates:\n\n- **Codebase**: All files, dependencies, and configuration at the moment of the fork.\n- **Database schema and data**: The cloned volume includes code and data at the moment of the fork.\n- **Chat summary**: The conversation up to the fork point is condensed into an editable Chat Summary, so the agent retains context about why the code exists.\n- **Build configuration**: Publishing settings and integrations.\n\n<Warning>\n**Secrets and API keys** are *not* copied for security reasons. You must re-add any required secrets (database URLs, third-party API keys) in the forked app's settings before publishing.\n</Warning>\n\n## When to Fork vs. Rollback\n\n| Scenario | Use |\n|----------|-----|\n| Undo a recent bad change | [Rollback](/checkpoints-undo-anything) |\n| Preserve the current app and try a big experiment | **Fork** |\n| Create a variant for a different customer or region | **Fork** |\n| Recover from multiple bad changes over time | Rollback to a known-good state, *then* fork if you want to try a different approach in parallel |\n\n## Managing Forked Apps\n\nForked apps consume credits independently. Each fork:\n\n- Runs its own [build jobs](/what-is-a-job) and incurs credit costs for agent work and published versions.\n- Maintains a separate database instance.\n- Appears in your workspace alongside the original.\n\n<Note>\nDelete forks you no longer need to avoid unnecessary credit usage and workspace clutter. Deleting a fork does not affect the original app.\n</Note>\n\n## Context Limits\n\nEvery chat - including the history in a forked app - operates within a **context window**: the maximum number of tokens (roughly words and code characters) the AI agent can \"see\" at once. Emergent uses models with large context windows, but even these have limits.\n\n### How to Work Within Context Limits\n\n- **Scope tasks narrowly**: Instead of \"refactor the entire app,\" ask for one feature or module at a time.\n- **Use multiple smaller projects**: If your app grows very large, consider splitting it into microservices or separate Emergent projects that communicate via APIs.\n- **Fork strategically**: Forking resets the *future* chat (you start fresh after the fork), but the agent still carries the summarized pre-fork history in the forked app's context. If context is tight, fork early rather than late.\n\n<Info>\nWhen you approach context limits, Emergent's **Infinite Chat** system (described below) automatically compacts older messages to keep the conversation going.\n</Info>\n\n## Infinite Chat (Auto Context Compaction)\n\nEmergent's **Infinite Chat** feature ensures long conversations never hit a hard wall. As your chat history grows, the platform automatically condenses older messages to free up space for new work.\n\n### How It Works\n\n<Steps>\n<Step title=\"Squash at ~70% capacity\">\nWhen the chat reaches approximately **70% of the context window**, Emergent **squashes** older messages: it combines consecutive user-assistant exchanges into summary blocks that preserve key decisions and code changes but remove redundant back-and-forth.\n</Step>\n\n<Step title=\"Auto-compact at ~82.5% capacity\">\nAt roughly **82.5% capacity**, the system performs a deeper **compaction**: it condenses multiple squashed blocks into high-level summaries, retaining architectural decisions and major feature descriptions while discarding fine-grained edits.\n</Step>\n\n<Step title=\"Truncation near 275K tokens\">\nIf the chat approaches **~275,000 tokens** (the effective hard limit), Emergent truncates the oldest compacted summaries. Critical information - recent changes, active feature requests, and the current codebase state - always remain.\n</Step>\n</Steps>\n\n<Tip>\nYou don't need to do anything to enable Infinite Chat. It runs automatically in the background, and you'll see a brief notification in the chat when compaction occurs.\n</Tip>\n\n### What This Means for You\n\n- **Long-lived projects work smoothly**: You can chat for weeks or months without manually restarting or losing context.\n- **Fork preserves pre-fork context**: A forked app inherits the summarized history up to the fork point, so the agent still \"remembers\" why the original code exists - but the fork's *future* chat starts fresh, giving you more headroom.\n- **Older details may fade**: After multiple compaction cycles, very early conversation details (e.g., initial brainstorming) may be summarized heavily. Keep important architectural notes in your codebase comments or README if you need them long-term.\n\n<Note>\nIf you ever feel the agent has \"forgotten\" something important, re-state the requirement explicitly in chat. The agent always prioritizes your most recent instructions.\n</Note>","order":16,"parent_id":null,"icon":"git-branch","description":"Forking an app to branch off into a separate app (with its own build/DB). See also Rollback in Build.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:57.263031+00:00","published_at":"2026-09-22T06:19:57.263031+00:00","published_content":"## What is Forking?\n\n**Forking** creates a complete, independent copy of your current app - including its entire codebase, database schema, and a summarized version of the chat history up to the fork point. The forked app runs as a separate project with its own build pipeline, database, and published app.\n\nUse forking when you want to:\n\n- Experiment with a major architectural change without risking your production app\n- Create a variant of an app for a different audience or use case\n- Preserve a stable snapshot before attempting risky refactors\n\n<Info>\nForking is different from [rollback](/checkpoints-undo-anything). Rollback rewinds your *current* app to an earlier state; forking creates a *new* app that diverges from the original.\n</Info>\n\n## How to Fork an App\n\n<Steps>\n<Step title=\"Open the Fork button\">\nIn the chat input bar (web only), click the **Fork** button to begin the forking process. This opens the Configure New Chat dialog.\n</Step>\n\n<Step title=\"Select Fork\">\nConfirm your fork settings in the Configure New Chat dialog. The platform will duplicate the app state - code and cloned volume (including data) - into a new project, with a summarized (editable) chat history.\n</Step>\n\n<Step title=\"Name the fork\">\nGive your fork a descriptive name (e.g., `MyApp - Experimental Redesign`) so you can distinguish it from the original.\n</Step>\n\n<Step title=\"Continue building\">\nThe forked app appears in your workspace as a standalone project. Chat, build, and publish independently. Changes to the fork do not affect the original app, and vice versa.\n</Step>\n</Steps>\n\n<Tip>\nFork *before* starting a risky change. If the experiment succeeds, you can continue with the fork; if it fails, simply delete the fork and return to the original.\n</Tip>\n\n## What Gets Copied\n\nWhen you fork an app, Emergent duplicates:\n\n- **Codebase**: All files, dependencies, and configuration at the moment of the fork.\n- **Database schema and data**: The cloned volume includes code and data at the moment of the fork.\n- **Chat summary**: The conversation up to the fork point is condensed into an editable Chat Summary, so the agent retains context about why the code exists.\n- **Build configuration**: Publishing settings and integrations.\n\n<Warning>\n**Secrets and API keys** are *not* copied for security reasons. You must re-add any required secrets (database URLs, third-party API keys) in the forked app's settings before publishing.\n</Warning>\n\n## When to Fork vs. Rollback\n\n| Scenario | Use |\n|----------|-----|\n| Undo a recent bad change | [Rollback](/checkpoints-undo-anything) |\n| Preserve the current app and try a big experiment | **Fork** |\n| Create a variant for a different customer or region | **Fork** |\n| Recover from multiple bad changes over time | Rollback to a known-good state, *then* fork if you want to try a different approach in parallel |\n\n## Managing Forked Apps\n\nForked apps consume credits independently. Each fork:\n\n- Runs its own [build jobs](/what-is-a-job) and incurs credit costs for agent work and published versions.\n- Maintains a separate database instance.\n- Appears in your workspace alongside the original.\n\n<Note>\nDelete forks you no longer need to avoid unnecessary credit usage and workspace clutter. Deleting a fork does not affect the original app.\n</Note>\n\n## Context Limits\n\nEvery chat - including the history in a forked app - operates within a **context window**: the maximum number of tokens (roughly words and code characters) the AI agent can \"see\" at once. Emergent uses models with large context windows, but even these have limits.\n\n### How to Work Within Context Limits\n\n- **Scope tasks narrowly**: Instead of \"refactor the entire app,\" ask for one feature or module at a time.\n- **Use multiple smaller projects**: If your app grows very large, consider splitting it into microservices or separate Emergent projects that communicate via APIs.\n- **Fork strategically**: Forking resets the *future* chat (you start fresh after the fork), but the agent still carries the summarized pre-fork history in the forked app's context. If context is tight, fork early rather than late.\n\n<Info>\nWhen you approach context limits, Emergent's **Infinite Chat** system (described below) automatically compacts older messages to keep the conversation going.\n</Info>\n\n## Infinite Chat (Auto Context Compaction)\n\nEmergent's **Infinite Chat** feature ensures long conversations never hit a hard wall. As your chat history grows, the platform automatically condenses older messages to free up space for new work.\n\n### How It Works\n\n<Steps>\n<Step title=\"Squash at ~70% capacity\">\nWhen the chat reaches approximately **70% of the context window**, Emergent **squashes** older messages: it combines consecutive user-assistant exchanges into summary blocks that preserve key decisions and code changes but remove redundant back-and-forth.\n</Step>\n\n<Step title=\"Auto-compact at ~82.5% capacity\">\nAt roughly **82.5% capacity**, the system performs a deeper **compaction**: it condenses multiple squashed blocks into high-level summaries, retaining architectural decisions and major feature descriptions while discarding fine-grained edits.\n</Step>\n\n<Step title=\"Truncation near 275K tokens\">\nIf the chat approaches **~275,000 tokens** (the effective hard limit), Emergent truncates the oldest compacted summaries. Critical information - recent changes, active feature requests, and the current codebase state - always remain.\n</Step>\n</Steps>\n\n<Tip>\nYou don't need to do anything to enable Infinite Chat. It runs automatically in the background, and you'll see a brief notification in the chat when compaction occurs.\n</Tip>\n\n### What This Means for You\n\n- **Long-lived projects work smoothly**: You can chat for weeks or months without manually restarting or losing context.\n- **Fork preserves pre-fork context**: A forked app inherits the summarized history up to the fork point, so the agent still \"remembers\" why the original code exists - but the fork's *future* chat starts fresh, giving you more headroom.\n- **Older details may fade**: After multiple compaction cycles, very early conversation details (e.g., initial brainstorming) may be summarized heavily. Keep important architectural notes in your codebase comments or README if you need them long-term.\n\n<Note>\nIf you ever feel the agent has \"forgotten\" something important, re-state the requirement explicitly in chat. The agent always prioritizes your most recent instructions.\n</Note>","published_title":"Forking","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"37676517-fb72-434f-8588-465417e9b8fc","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"The Universal LLM Key","slug":"the-universal-llm-key","content":"## What is the Universal LLM Key?\n\nThe Universal LLM Key is a single API key that gives your projects access to 44+ language models across 7 providers, including current Claude, GPT, and Gemini model families, without requiring you to sign up for separate API accounts or manage individual keys for each provider.\n\nInstead of juggling credentials from multiple AI providers, you use your **Emergent Credits** to fund model calls through the Universal Key. The platform handles routing, authentication, and billing automatically with **no markup**, you pay the platform's per-token rates from your credit balance.\n\n<Note title=\"Generate your key in Account Settings\">\nThe Universal LLM Key is managed in **Account Settings → Universal API Key**. You generate it yourself, it is not created automatically. Keys start with the prefix **`sk-emergent-`**. Access to advanced controls (rate-limit overrides, external proxy, etc.) requires a **Standard or Pro** plan; Free accounts are blocked from compute-intensive models.\n</Note>\n\nThe key works inside your published apps, and on paid plans you can also use it as a **LiteLLM-compatible proxy** from your local machine or CI/CD pipelines.\n\n---\n\n## Universal Key vs Your Own API Key\n\nYou have two options for connecting your projects to language models:\n\n| Aspect | Universal Key | Your Own API Key |\n|--------|--------------|------------------|\n| **Setup** | Generate once in Account Settings; no external accounts | Must create accounts with each AI provider |\n| **Billing** | Charged in Emergent Credits; single balance | Billed directly by each provider |\n| **Model access** | 44+ models / 7 providers via one key | Only models from the provider you signed up with |\n| **Rate limits** | Shared platform limits | Provider's limits for your account tier |\n| **Cost transparency** | Unified credit usage dashboard | Separate invoices from each provider |\n| **Markup** | No markup on platform per-token rates | Provider list price |\n\n### When to use the Universal Key\n\n- You're prototyping and want to try multiple models quickly\n- You prefer consolidated billing and credit management\n- You're building internal tools and don't want to manage external API keys\n- You value simplicity over per-token cost optimization\n\n### When to bring your own key\n\n- You've negotiated volume discounts with a specific provider\n- You need model access beyond Emergent's supported set\n- Your organization mandates direct contracts with AI providers\n\nTo bring your own LLM credentials, go to **Account Settings → Universal API Key → Custom LLM Keys**.\n\n<Tip title=\"Switching is easy\">\nYou can start with the Universal Key and switch to your own API keys later by updating your project's [Secrets](/secrets-env-variables). The agent will adapt automatically.\n</Tip>\n\n---\n\n## Recharging & Credit Types\n\nThe Universal Key draws from your **Emergent Credit balance** every time your app makes a model call. When your balance runs low, you'll need to recharge to keep services running.\n\n### How recharging works\n\n<Steps>\n<Step title=\"Check your balance\">\nView your current credit balance and usage history in **Account Settings → Credit Usage**.\n</Step>\n\n<Step title=\"Add credits\">\nPurchase credits via your supported payment provider. Credits are added to your single combined balance instantly.\n</Step>\n\n<Step title=\"Credits are consumed\">\nEach model call deducts credits based on token count and model pricing. You can see per-project breakdowns in the usage dashboard.\n</Step>\n</Steps>\n\n### Credit types\n\n- **Subscription credits**: Included with your paid plan each billing cycle; these do **not** roll over, they refill to the plan cap at each cycle.\n- **Purchased (top-up) credits**: Pay-as-you-go; these **never expire**.\n- **Promotional/boost credits**: Carry a shown fixed expiry date; applied before other credit types.\n\nFor full details on credit expiry and rollover rules, see [Managing credit usage](/managing-credit-usage).\n\n<Info title=\"Auto-recharge available\">\nPaid plans can enable **auto-recharge** to prevent service interruptions. When your balance drops below the configurable trigger threshold (minimum **5 credits**), the platform automatically **transfers funds from your Emergent credit balance** to keep the Universal Key funded. Purchase-based auto-topup (charging your card automatically) is coming soon.\n</Info>\n\n---\n\n## Using the Key Outside the Platform\n\nOn **paid plans**, you can use your Universal Key as a **LiteLLM-compatible proxy endpoint** to call models from your local development environment, scripts, or CI/CD pipelines.\n\nThe proxy base URL and full configuration details are shown in **Account Settings → Universal API Key** after you generate your key.\n\n### Setup example\n\n<CodeGroup>\n```python Python (OpenAI SDK)\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"sk-emergent-YOUR_KEY_HERE\",\n    base_url=\"<base_url_from_account_settings>\"\n)\n\nresponse = client.chat.completions.create(\n    model=\"<model-name>\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\nprint(response.choices[0].message.content)\n```\n\n```bash cURL\ncurl <base_url_from_account_settings>/chat/completions \\\n  -H \"Authorization: Bearer sk-emergent-YOUR_KEY_HERE\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model-name>\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]\n  }'\n```\n</CodeGroup>\n\n<Note title=\"Find your base URL\">\nThe exact proxy base URL is displayed in **Account Settings → Universal API Key**. Replace `<base_url_from_account_settings>` with the value shown there.\n</Note>\n\n<Warning title=\"Free tier limitation\">\nThe external proxy endpoint is **not available on the Free tier**, and Free accounts are blocked from compute-intensive models. Upgrade to **Standard or Pro** to use the Universal Key outside of published Emergent apps and to access advanced controls.\n</Warning>\n\nFor security, the Universal Key proxy is **IP-restricted**. Requests must originate from known Emergent infrastructure or your verified NAT gateway. If you're on a dynamic IP, the platform may prompt you to verify your location the first time you call from a new network. Enterprise plans can whitelist specific CIDR ranges for CI/CD runners.\n\n---\n\n## Regenerating the Key Breaks Live Apps\n\nYour Universal Key is tied directly to your account and embedded in your published applications as the Secret **`EMERGENT_LLM_KEY`**. If you regenerate it (for example, after a suspected leak), the old key is **immediately invalidated**.\n\n<Callout type=\"error\" title=\"Published apps will fail\">\nAny live app that references the old Universal Key will start receiving **401 Unauthorized** errors as soon as you regenerate. This includes:\n\n- Apps making LLM calls via the Emergent SDK\n- Integrations that use the key via the `EMERGENT_LLM_KEY` environment variable\n- External scripts or services using the old key\n</Callout>\n\n### Recovery steps\n\n<Steps>\n<Step title=\"Regenerate the key\">\nGo to **Account Settings → Universal API Key** and regenerate your key. Copy the new `sk-emergent-…` key immediately.\n</Step>\n\n<Step title=\"Update Secrets\">\nFor each affected project, open **Preview → Manage → Secrets**, find the `EMERGENT_LLM_KEY` entry, and paste the new key value.\n</Step>\n\n<Step title=\"Re-publish\">\nTrigger a **Re-publish** so the updated Secret propagates to the live environment. Re-publishing is free of charge (beyond the monthly tier fee) .\n</Step>\n</Steps>\n\n<Tip title=\"Test in preview first\">\nIf your project has a preview environment, update the Secret there first and verify everything works before updating production. Note that preview and production environment variables are managed separately after the first publish.\n</Tip>\n\n### When to regenerate\n\nOnly regenerate your Universal Key if:\n\n- You believe the key has been exposed publicly (e.g., committed to a public repo)\n- An ex-team member had access and you need to revoke it immediately\n- You're responding to a security incident\n\nFor routine key rotation, coordinate the regeneration with a maintenance window to minimize downtime.\n\n---\n\n## Supported Models\n\nThe Universal Key currently provides access to **44+ models across 7 providers**. Current model families include:\n\n- **Claude**: Fable 5.x / Opus 5 / Sonnet 5 / 4.6 / Haiku 4.5\n- **GPT**: GPT-6 / GPT-5.x\n- **Gemini**: 2.5-3.8\n\nThe full, up-to-date list of available models is shown in **Account Settings → Universal API Key**.\n\n<Note title=\"Free tier model restrictions\">\nFree accounts are blocked from compute-intensive models. Upgrade to **Standard or Pro** to unlock the full model catalog.\n</Note>","order":19,"parent_id":null,"icon":"key","description":"The Universal LLM Key","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T09:00:52.751542+00:00","published_at":"2026-09-25T09:00:52.751542+00:00","published_content":"## What is the Universal LLM Key?\n\nThe Universal LLM Key is a single API key that gives your projects access to 44+ language models across 7 providers, including current Claude, GPT, and Gemini model families, without requiring you to sign up for separate API accounts or manage individual keys for each provider.\n\nInstead of juggling credentials from multiple AI providers, you use your **Emergent Credits** to fund model calls through the Universal Key. The platform handles routing, authentication, and billing automatically with **no markup**, you pay the platform's per-token rates from your credit balance.\n\n<Note title=\"Generate your key in Account Settings\">\nThe Universal LLM Key is managed in **Account Settings → Universal API Key**. You generate it yourself, it is not created automatically. Keys start with the prefix **`sk-emergent-`**. Access to advanced controls (rate-limit overrides, external proxy, etc.) requires a **Standard or Pro** plan; Free accounts are blocked from compute-intensive models.\n</Note>\n\nThe key works inside your published apps, and on paid plans you can also use it as a **LiteLLM-compatible proxy** from your local machine or CI/CD pipelines.\n\n---\n\n## Universal Key vs Your Own API Key\n\nYou have two options for connecting your projects to language models:\n\n| Aspect | Universal Key | Your Own API Key |\n|--------|--------------|------------------|\n| **Setup** | Generate once in Account Settings; no external accounts | Must create accounts with each AI provider |\n| **Billing** | Charged in Emergent Credits; single balance | Billed directly by each provider |\n| **Model access** | 44+ models / 7 providers via one key | Only models from the provider you signed up with |\n| **Rate limits** | Shared platform limits | Provider's limits for your account tier |\n| **Cost transparency** | Unified credit usage dashboard | Separate invoices from each provider |\n| **Markup** | No markup on platform per-token rates | Provider list price |\n\n### When to use the Universal Key\n\n- You're prototyping and want to try multiple models quickly\n- You prefer consolidated billing and credit management\n- You're building internal tools and don't want to manage external API keys\n- You value simplicity over per-token cost optimization\n\n### When to bring your own key\n\n- You've negotiated volume discounts with a specific provider\n- You need model access beyond Emergent's supported set\n- Your organization mandates direct contracts with AI providers\n\nTo bring your own LLM credentials, go to **Account Settings → Universal API Key → Custom LLM Keys**.\n\n<Tip title=\"Switching is easy\">\nYou can start with the Universal Key and switch to your own API keys later by updating your project's [Secrets](/secrets-env-variables). The agent will adapt automatically.\n</Tip>\n\n---\n\n## Recharging & Credit Types\n\nThe Universal Key draws from your **Emergent Credit balance** every time your app makes a model call. When your balance runs low, you'll need to recharge to keep services running.\n\n### How recharging works\n\n<Steps>\n<Step title=\"Check your balance\">\nView your current credit balance and usage history in **Account Settings → Credit Usage**.\n</Step>\n\n<Step title=\"Add credits\">\nPurchase credits via your supported payment provider. Credits are added to your single combined balance instantly.\n</Step>\n\n<Step title=\"Credits are consumed\">\nEach model call deducts credits based on token count and model pricing. You can see per-project breakdowns in the usage dashboard.\n</Step>\n</Steps>\n\n### Credit types\n\n- **Subscription credits**: Included with your paid plan each billing cycle; these do **not** roll over, they refill to the plan cap at each cycle.\n- **Purchased (top-up) credits**: Pay-as-you-go; these **never expire**.\n- **Promotional/boost credits**: Carry a shown fixed expiry date; applied before other credit types.\n\nFor full details on credit expiry and rollover rules, see [Managing credit usage](/managing-credit-usage).\n\n<Info title=\"Auto-recharge available\">\nPaid plans can enable **auto-recharge** to prevent service interruptions. When your balance drops below the configurable trigger threshold (minimum **5 credits**), the platform automatically **transfers funds from your Emergent credit balance** to keep the Universal Key funded. Purchase-based auto-topup (charging your card automatically) is coming soon.\n</Info>\n\n---\n\n## Using the Key Outside the Platform\n\nOn **paid plans**, you can use your Universal Key as a **LiteLLM-compatible proxy endpoint** to call models from your local development environment, scripts, or CI/CD pipelines.\n\nThe proxy base URL and full configuration details are shown in **Account Settings → Universal API Key** after you generate your key.\n\n### Setup example\n\n<CodeGroup>\n```python Python (OpenAI SDK)\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"sk-emergent-YOUR_KEY_HERE\",\n    base_url=\"<base_url_from_account_settings>\"\n)\n\nresponse = client.chat.completions.create(\n    model=\"<model-name>\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\nprint(response.choices[0].message.content)\n```\n\n```bash cURL\ncurl <base_url_from_account_settings>/chat/completions \\\n  -H \"Authorization: Bearer sk-emergent-YOUR_KEY_HERE\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"<model-name>\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]\n  }'\n```\n</CodeGroup>\n\n<Note title=\"Find your base URL\">\nThe exact proxy base URL is displayed in **Account Settings → Universal API Key**. Replace `<base_url_from_account_settings>` with the value shown there.\n</Note>\n\n<Warning title=\"Free tier limitation\">\nThe external proxy endpoint is **not available on the Free tier**, and Free accounts are blocked from compute-intensive models. Upgrade to **Standard or Pro** to use the Universal Key outside of published Emergent apps and to access advanced controls.\n</Warning>\n\nFor security, the Universal Key proxy is **IP-restricted**. Requests must originate from known Emergent infrastructure or your verified NAT gateway. If you're on a dynamic IP, the platform may prompt you to verify your location the first time you call from a new network. Enterprise plans can whitelist specific CIDR ranges for CI/CD runners.\n\n---\n\n## Regenerating the Key Breaks Live Apps\n\nYour Universal Key is tied directly to your account and embedded in your published applications as the Secret **`EMERGENT_LLM_KEY`**. If you regenerate it (for example, after a suspected leak), the old key is **immediately invalidated**.\n\n<Callout type=\"error\" title=\"Published apps will fail\">\nAny live app that references the old Universal Key will start receiving **401 Unauthorized** errors as soon as you regenerate. This includes:\n\n- Apps making LLM calls via the Emergent SDK\n- Integrations that use the key via the `EMERGENT_LLM_KEY` environment variable\n- External scripts or services using the old key\n</Callout>\n\n### Recovery steps\n\n<Steps>\n<Step title=\"Regenerate the key\">\nGo to **Account Settings → Universal API Key** and regenerate your key. Copy the new `sk-emergent-…` key immediately.\n</Step>\n\n<Step title=\"Update Secrets\">\nFor each affected project, open **Preview → Manage → Secrets**, find the `EMERGENT_LLM_KEY` entry, and paste the new key value.\n</Step>\n\n<Step title=\"Re-publish\">\nTrigger a **Re-publish** so the updated Secret propagates to the live environment. Re-publishing is free of charge (beyond the monthly tier fee) .\n</Step>\n</Steps>\n\n<Tip title=\"Test in preview first\">\nIf your project has a preview environment, update the Secret there first and verify everything works before updating production. Note that preview and production environment variables are managed separately after the first publish.\n</Tip>\n\n### When to regenerate\n\nOnly regenerate your Universal Key if:\n\n- You believe the key has been exposed publicly (e.g., committed to a public repo)\n- An ex-team member had access and you need to revoke it immediately\n- You're responding to a security incident\n\nFor routine key rotation, coordinate the regeneration with a maintenance window to minimize downtime.\n\n---\n\n## Supported Models\n\nThe Universal Key currently provides access to **44+ models across 7 providers**. Current model families include:\n\n- **Claude**: Fable 5.x / Opus 5 / Sonnet 5 / 4.6 / Haiku 4.5\n- **GPT**: GPT-6 / GPT-5.x\n- **Gemini**: 2.5-3.8\n\nThe full, up-to-date list of available models is shown in **Account Settings → Universal API Key**.\n\n<Note title=\"Free tier model restrictions\">\nFree accounts are blocked from compute-intensive models. Upgrade to **Standard or Pro** to unlock the full model catalog.\n</Note>","published_title":"The Universal LLM Key","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"d9d26da3-5405-4320-8396-417894017570","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Pre-publish health check for web apps","slug":"pre-deploy-pre-publish-health-check","content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Before you publish\n\nLooking for the beginner version? See [Try it before you share it](/try-it-before-you-share-it).\n\nEvery publish (web or mobile) is a published snapshot of your app. Taking a few minutes to verify readiness before you ship will save hours of firefighting later.\n\n<Note title=\"Preview ≠ production\">\nThe [preview environment](/preview-vs-deployed-separate) runs your latest code in development mode. Published app creates a separate, optimized production build - so always test the *published* version after your first publish.\n</Note>\n\n---\n\n## Preview and test thoroughly\n\nBefore you hit publish, exercise your app as a real user would.\n\n<Steps>\n\n<Step title=\"Test all core features\">\nWalk through your primary user flows end-to-end: sign-up, login, main actions, checkout, etc. Confirm buttons trigger the right actions, forms validate correctly, and data saves as expected.\n</Step>\n\n<Step title=\"Check responsiveness\">\nResize your browser (or use dev tools device emulation) to confirm layouts adapt cleanly from mobile to tablet to desktop. Text should remain readable, buttons tappable, and images properly scaled.\n</Step>\n\n<Step title=\"Test interactivity and state\">\nOpen dropdowns, modals, tabs, and drawers. Verify animations play smoothly, loading spinners appear during async work, and error messages show when they should.\n</Step>\n\n<Step title=\"On-device testing for mobile apps\">\nIf you are publishing a mobile app, install the preview build on a real device (iOS or Android) via Expo Go (free, no paid plan required; TestFlight/APK native builds require a paid Emergent plan). Touch targets, scrolling behavior, keyboard handling, and camera/gallery permissions all behave differently on real hardware.\n</Step>\n\n</Steps>\n\n<Tip>\nAsk a colleague or friend to try the preview - fresh eyes catch usability issues you've become blind to.\n</Tip>\n\n---\n\n## Pre-publish readiness checklist\n\nBefore you publish to production, confirm each item below.\n\n### Technical readiness\n\n<AccordionGroup>\n\n<Accordion title=\"Environment variables and secrets\">\nEnsure production API keys, database credentials, and third-party service tokens are set in your publish environment (not hardcoded). The [Universal LLM Key](/the-universal-llm-key) is included by default; add any additional keys your app requires.\n</Accordion>\n\n<Accordion title=\"Database migrations and seed data\">\nIf your app uses [MongoDB](/database-mongodb) or another data store, confirm schema changes are applied and any required seed data (categories, initial settings, etc.) is present in production. Re-publish never moves data from preview to production (only the first publish does), so if you add data or change the schema after the first publish in preview it won't be reflected in the production database.\n</Accordion>\n\n<Accordion title=\"Authentication flows\">\nTest sign-up, login, and logout with real email addresses. Verify email delivery (check spam folders), session persistence, and protected route behavior.\n</Accordion>\n\n<Accordion title=\"Third-party integrations\">\nConfirm payment gateways, email services, analytics, and any external APIs are configured with production credentials and return expected responses.\n</Accordion>\n\n<Accordion title=\"Error handling\">\nDeliberately trigger error states (invalid form input, network failures, missing resources) and confirm your app shows helpful messages rather than crashing or hanging.\n</Accordion>\n\n</AccordionGroup>\n\n### Content and polish\n\n| Item | What to check |\n|------|---------------|\n| **Copy and spelling** | Scan visible text for typos, placeholder \"lorem ipsum,\" and broken grammar. |\n| **Images and assets** | Verify all images load, logos are high-resolution, and icons are consistent. |\n| **Branding** | Confirm app name, favicon, and splash screen reflect your final brand. |\n| **Legal pages** | Include privacy policy, terms of service, and any required disclaimers. |\n\n### Performance and SEO (web)\n\n<AccordionGroup>\n\n<Accordion title=\"Page load speed\">\nOpen your preview in an incognito window and watch the initial render. If it feels sluggish, investigate large images, heavy third-party scripts, or unoptimized bundles.\n</Accordion>\n\n<Accordion title=\"Meta tags and Open Graph\">\nConfirm page titles, descriptions, and social share images (`og:image`, `twitter:card`) are set so links preview well when shared.\n</Accordion>\n\n<Accordion title=\"Mobile viewport meta tag\">\nVerify `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">` is present so mobile browsers render at the correct scale.\n</Accordion>\n\n</AccordionGroup>\n\n### Mobile-specific (iOS and Android)\n\n<AccordionGroup>\n\n<Accordion title=\"App store metadata\">\nPrepare your app name, description, screenshots, category, and keywords. Have your icon ready in all required sizes (iOS needs 1024×1024, Android needs adaptive icon layers).\n</Accordion>\n\n<Accordion title=\"Permissions and capabilities\">\nEnsure your app requests only the permissions it actually uses (camera, location, notifications, etc.) and include usage descriptions that explain *why* each permission is needed.\n</Accordion>\n\n<Accordion title=\"Platform-specific testing\">\nTest on both iOS and Android devices if you are building cross-platform. Pay attention to status bar styling, safe area insets, back-button behavior, and keyboard dismissal.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Published app confidence checklist\n\nRight before you click \"Publish,\" confirm:\n\n- [ ] **You have tested in preview** and fixed any obvious bugs.\n- [ ] **Environment variables are set** for production.\n- [ ] **Database and backend services are live** and accessible.\n- [ ] **Core user flows work end-to-end** (sign-up, main feature, checkout, etc.).\n- [ ] **Branding, copy, and legal pages** are final and proofread.\n- [ ] **(Web)** Meta tags, favicon, and custom domain (if using) are configured. See [custom domain](/custom-domain).\n- [ ] **(Mobile)** App store assets and permissions are ready.\n\n<Success>\nWhen you can check every box above, you are ready to ship. Publish with confidence - and remember you can always push updates if you discover something after launch.\n</Success>\n\n---\n\n## After you publish\n\nOnce your app is live, verify the published build behaves identically to preview. The [preview and published environments](/preview-vs-deployed-separate) are separate, so it is normal to see a production URL (web) or a new build number (mobile).\n\nMonitor user feedback, error logs, and analytics for the first few hours. Early adopters will often surface edge cases you missed in testing.\n\n<Tip title=\"Keep iterating\">\nEvery publish is a snapshot - not a finish line. Use real-world usage to guide your next round of improvements.\n</Tip>","order":20,"parent_id":null,"icon":"shield-check","description":"1. Preview & test thoroughly first (features, responsiveness, interactivity / on-device for mobile).","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:07:38.773127+00:00","published_at":"2026-10-05T14:07:38.773127+00:00","published_content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n> New to Emergent? The **Learn the Basics** path walks this end-to-end.\n\n## Before you publish\n\nLooking for the beginner version? See [Try it before you share it](/try-it-before-you-share-it).\n\nEvery publish (web or mobile) is a published snapshot of your app. Taking a few minutes to verify readiness before you ship will save hours of firefighting later.\n\n<Note title=\"Preview ≠ production\">\nThe [preview environment](/preview-vs-deployed-separate) runs your latest code in development mode. Published app creates a separate, optimized production build - so always test the *published* version after your first publish.\n</Note>\n\n---\n\n## Preview and test thoroughly\n\nBefore you hit publish, exercise your app as a real user would.\n\n<Steps>\n\n<Step title=\"Test all core features\">\nWalk through your primary user flows end-to-end: sign-up, login, main actions, checkout, etc. Confirm buttons trigger the right actions, forms validate correctly, and data saves as expected.\n</Step>\n\n<Step title=\"Check responsiveness\">\nResize your browser (or use dev tools device emulation) to confirm layouts adapt cleanly from mobile to tablet to desktop. Text should remain readable, buttons tappable, and images properly scaled.\n</Step>\n\n<Step title=\"Test interactivity and state\">\nOpen dropdowns, modals, tabs, and drawers. Verify animations play smoothly, loading spinners appear during async work, and error messages show when they should.\n</Step>\n\n<Step title=\"On-device testing for mobile apps\">\nIf you are publishing a mobile app, install the preview build on a real device (iOS or Android) via Expo Go (free, no paid plan required; TestFlight/APK native builds require a paid Emergent plan). Touch targets, scrolling behavior, keyboard handling, and camera/gallery permissions all behave differently on real hardware.\n</Step>\n\n</Steps>\n\n<Tip>\nAsk a colleague or friend to try the preview - fresh eyes catch usability issues you've become blind to.\n</Tip>\n\n---\n\n## Pre-publish readiness checklist\n\nBefore you publish to production, confirm each item below.\n\n### Technical readiness\n\n<AccordionGroup>\n\n<Accordion title=\"Environment variables and secrets\">\nEnsure production API keys, database credentials, and third-party service tokens are set in your publish environment (not hardcoded). The [Universal LLM Key](/the-universal-llm-key) is included by default; add any additional keys your app requires.\n</Accordion>\n\n<Accordion title=\"Database migrations and seed data\">\nIf your app uses [MongoDB](/database-mongodb) or another data store, confirm schema changes are applied and any required seed data (categories, initial settings, etc.) is present in production. Re-publish never moves data from preview to production (only the first publish does), so if you add data or change the schema after the first publish in preview it won't be reflected in the production database.\n</Accordion>\n\n<Accordion title=\"Authentication flows\">\nTest sign-up, login, and logout with real email addresses. Verify email delivery (check spam folders), session persistence, and protected route behavior.\n</Accordion>\n\n<Accordion title=\"Third-party integrations\">\nConfirm payment gateways, email services, analytics, and any external APIs are configured with production credentials and return expected responses.\n</Accordion>\n\n<Accordion title=\"Error handling\">\nDeliberately trigger error states (invalid form input, network failures, missing resources) and confirm your app shows helpful messages rather than crashing or hanging.\n</Accordion>\n\n</AccordionGroup>\n\n### Content and polish\n\n| Item | What to check |\n|------|---------------|\n| **Copy and spelling** | Scan visible text for typos, placeholder \"lorem ipsum,\" and broken grammar. |\n| **Images and assets** | Verify all images load, logos are high-resolution, and icons are consistent. |\n| **Branding** | Confirm app name, favicon, and splash screen reflect your final brand. |\n| **Legal pages** | Include privacy policy, terms of service, and any required disclaimers. |\n\n### Performance and SEO (web)\n\n<AccordionGroup>\n\n<Accordion title=\"Page load speed\">\nOpen your preview in an incognito window and watch the initial render. If it feels sluggish, investigate large images, heavy third-party scripts, or unoptimized bundles.\n</Accordion>\n\n<Accordion title=\"Meta tags and Open Graph\">\nConfirm page titles, descriptions, and social share images (`og:image`, `twitter:card`) are set so links preview well when shared.\n</Accordion>\n\n<Accordion title=\"Mobile viewport meta tag\">\nVerify `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">` is present so mobile browsers render at the correct scale.\n</Accordion>\n\n</AccordionGroup>\n\n### Mobile-specific (iOS and Android)\n\n<AccordionGroup>\n\n<Accordion title=\"App store metadata\">\nPrepare your app name, description, screenshots, category, and keywords. Have your icon ready in all required sizes (iOS needs 1024×1024, Android needs adaptive icon layers).\n</Accordion>\n\n<Accordion title=\"Permissions and capabilities\">\nEnsure your app requests only the permissions it actually uses (camera, location, notifications, etc.) and include usage descriptions that explain *why* each permission is needed.\n</Accordion>\n\n<Accordion title=\"Platform-specific testing\">\nTest on both iOS and Android devices if you are building cross-platform. Pay attention to status bar styling, safe area insets, back-button behavior, and keyboard dismissal.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Published app confidence checklist\n\nRight before you click \"Publish,\" confirm:\n\n- [ ] **You have tested in preview** and fixed any obvious bugs.\n- [ ] **Environment variables are set** for production.\n- [ ] **Database and backend services are live** and accessible.\n- [ ] **Core user flows work end-to-end** (sign-up, main feature, checkout, etc.).\n- [ ] **Branding, copy, and legal pages** are final and proofread.\n- [ ] **(Web)** Meta tags, favicon, and custom domain (if using) are configured. See [custom domain](/custom-domain).\n- [ ] **(Mobile)** App store assets and permissions are ready.\n\n<Success>\nWhen you can check every box above, you are ready to ship. Publish with confidence - and remember you can always push updates if you discover something after launch.\n</Success>\n\n---\n\n## After you publish\n\nOnce your app is live, verify the published build behaves identically to preview. The [preview and published environments](/preview-vs-deployed-separate) are separate, so it is normal to see a production URL (web) or a new build number (mobile).\n\nMonitor user feedback, error logs, and analytics for the first few hours. Early adopters will often surface edge cases you missed in testing.\n\n<Tip title=\"Keep iterating\">\nEvery publish is a snapshot - not a finish line. Use real-world usage to guide your next round of improvements.\n</Tip>","published_title":"Pre-publish health check for web apps","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"7402e478-f153-4dea-8c08-e367a56fd5a9","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Secrets & env variables","slug":"secrets-env-variables","content":"## Overview\n\nSecrets and environment variables let your published app access API keys, database credentials, and other sensitive configuration without hardcoding them in your codebase.\n\nEmergent provides a built-in **secrets manager** for every project. Store your secrets there, not in files committed to your repository.\n\n<Warning title=\"Secrets work in preview and published environments\">\nThe secrets manager is designed for **preview and published** applications. During the build phase in chat, agents use the [Universal LLM Key](/the-universal-llm-key) and test credentials. Your secrets become available in both preview and published environments.\n</Warning>\n\n---\n\n## Where to store secrets\n\n<Steps>\n<Step title=\"Open the secrets manager\">\nIn your workspace, navigate to the **Secrets** panel (Click **Preview**, then **Manage**, you can see the **Secrets** panel there).\n</Step>\n\n<Step title=\"Add or edit keys\">\nTo add a **new** key, ask the agent to add it to your `.env` file, then re-publish. Once a key exists, you can **edit its value** directly in the Secrets UI (**Preview → Manage → Secrets**). The value will be masked in the UI after you save, but can be revealed or copied by anyone with published app access.\n</Step>\n\n<Step title=\"Save\">\nClick **Save** to store the secret. It is now encrypted and associated with your project.\n</Step>\n</Steps>\n\n<Note>\nThe `.env` file is the platform's canonical mechanism for managing environment variables and is auto-excluded from GitHub pushes, so credentials are kept out of version control and logs.\n</Note>\n\n---\n\n## Accessing secrets in your app\n\nYour application reads secrets as **environment variables** at runtime:\n\n<CodeGroup>\n```javascript Node.js / Next.js\nconst apiKey = process.env.OPENAI_API_KEY;\n```\n\n```python Python / Flask\nimport os\napi_key = os.environ.get(\"OPENAI_API_KEY\")\n```\n\n```bash Shell / Docker\necho $OPENAI_API_KEY\n```\n</CodeGroup>\n\nThe platform injects these variables into your app's container when it starts.\n\n---\n\n## Re-publishing after adding or changing secrets\n\n<Warning title=\"Saving alone does not update your live app\">\nA newly saved or updated secret **will not take effect** in a running published app until you **re-publish**.\n</Warning>\n\n**Why?** Your published container was built with the secrets available at published app time. Changing a secret in the manager updates the stored value but does not restart or reconfigure running instances.\n\n### How to apply updated secrets\n\n1. Save your new or modified secret in the secrets manager.\n2. Trigger a **re-publish** (re-publish) from the workspace or via chat (e.g. \"re-publish the app\").\n3. The new container starts with the updated environment variables.\n\n<Tip>\nIf your app isn't picking up a secret, confirm you've republished since the last save. Check the published app timestamp in your workspace.\n</Tip>\n\n---\n\n## Common pitfalls\n\n<AccordionGroup>\n<Accordion title=\"I saved a secret but my app still can't connect to the database\">\n**Solution:** Re-publish the app. The running container uses the secrets from the last published app, not the latest saved values.\n</Accordion>\n\n<Accordion title=\"Can I see the value of a secret after I save it?\">\nYes. The secrets manager masks values by default, but a per-line reveal toggle and click-to-copy are available. Note that values are visible to anyone with published app access. To correct a key's value, edit it directly in the Secrets UI. Note that keys cannot be deleted from the UI, if you need to stop using a key, update its value and re-publish.\n</Accordion>\n\n<Accordion title=\"Do secrets sync to GitHub?\">\nNo. Secrets live only in the Emergent platform. If you use [Save to GitHub](/save-to-github), your repository will not contain the secret values. You must configure secrets separately in any external CI/CD or hosting environment.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Best practices\n\n- **Use descriptive names**: `STRIPE_SECRET_KEY` is clearer than `KEY_1`.\n- **Rotate credentials regularly**: Update secrets in the manager, then re-publish.\n- **One secret per variable**: Avoid concatenating multiple keys into a single environment variable.\n- **Test after publish**: Confirm your app can read the secret by checking logs or a health endpoint.\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"The chat-to-published app flow\" icon=\"messages\" href=\"/the-chat-to-published app-flow\">\nUnderstand how build and publish phases handle credentials\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nConfigure your MongoDB connection string as a secret\n</Card>\n\n<Card title=\"The Universal LLM Key\" icon=\"key\" href=\"/the-universal-llm-key\">\nLearn how agents access LLMs during the build phase\n</Card>\n\n<Card title=\"App slow, crashing or cold-starting\" icon=\"triangle-alert\" href=\"/app-slow-crashing-or-cold-starting\">\nTroubleshoot runtime issues, including missing secrets\n</Card>\n</CardGroup>","order":21,"parent_id":null,"icon":"lock","description":"1. Where secrets go: use the secrets manager, not files in the repo.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:14.803938+00:00","published_at":"2026-09-22T06:20:14.803938+00:00","published_content":"## Overview\n\nSecrets and environment variables let your published app access API keys, database credentials, and other sensitive configuration without hardcoding them in your codebase.\n\nEmergent provides a built-in **secrets manager** for every project. Store your secrets there, not in files committed to your repository.\n\n<Warning title=\"Secrets work in preview and published environments\">\nThe secrets manager is designed for **preview and published** applications. During the build phase in chat, agents use the [Universal LLM Key](/the-universal-llm-key) and test credentials. Your secrets become available in both preview and published environments.\n</Warning>\n\n---\n\n## Where to store secrets\n\n<Steps>\n<Step title=\"Open the secrets manager\">\nIn your workspace, navigate to the **Secrets** panel (Click **Preview**, then **Manage**, you can see the **Secrets** panel there).\n</Step>\n\n<Step title=\"Add or edit keys\">\nTo add a **new** key, ask the agent to add it to your `.env` file, then re-publish. Once a key exists, you can **edit its value** directly in the Secrets UI (**Preview → Manage → Secrets**). The value will be masked in the UI after you save, but can be revealed or copied by anyone with published app access.\n</Step>\n\n<Step title=\"Save\">\nClick **Save** to store the secret. It is now encrypted and associated with your project.\n</Step>\n</Steps>\n\n<Note>\nThe `.env` file is the platform's canonical mechanism for managing environment variables and is auto-excluded from GitHub pushes, so credentials are kept out of version control and logs.\n</Note>\n\n---\n\n## Accessing secrets in your app\n\nYour application reads secrets as **environment variables** at runtime:\n\n<CodeGroup>\n```javascript Node.js / Next.js\nconst apiKey = process.env.OPENAI_API_KEY;\n```\n\n```python Python / Flask\nimport os\napi_key = os.environ.get(\"OPENAI_API_KEY\")\n```\n\n```bash Shell / Docker\necho $OPENAI_API_KEY\n```\n</CodeGroup>\n\nThe platform injects these variables into your app's container when it starts.\n\n---\n\n## Re-publishing after adding or changing secrets\n\n<Warning title=\"Saving alone does not update your live app\">\nA newly saved or updated secret **will not take effect** in a running published app until you **re-publish**.\n</Warning>\n\n**Why?** Your published container was built with the secrets available at published app time. Changing a secret in the manager updates the stored value but does not restart or reconfigure running instances.\n\n### How to apply updated secrets\n\n1. Save your new or modified secret in the secrets manager.\n2. Trigger a **re-publish** (re-publish) from the workspace or via chat (e.g. \"re-publish the app\").\n3. The new container starts with the updated environment variables.\n\n<Tip>\nIf your app isn't picking up a secret, confirm you've republished since the last save. Check the published app timestamp in your workspace.\n</Tip>\n\n---\n\n## Common pitfalls\n\n<AccordionGroup>\n<Accordion title=\"I saved a secret but my app still can't connect to the database\">\n**Solution:** Re-publish the app. The running container uses the secrets from the last published app, not the latest saved values.\n</Accordion>\n\n<Accordion title=\"Can I see the value of a secret after I save it?\">\nYes. The secrets manager masks values by default, but a per-line reveal toggle and click-to-copy are available. Note that values are visible to anyone with published app access. To correct a key's value, edit it directly in the Secrets UI. Note that keys cannot be deleted from the UI, if you need to stop using a key, update its value and re-publish.\n</Accordion>\n\n<Accordion title=\"Do secrets sync to GitHub?\">\nNo. Secrets live only in the Emergent platform. If you use [Save to GitHub](/save-to-github), your repository will not contain the secret values. You must configure secrets separately in any external CI/CD or hosting environment.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Best practices\n\n- **Use descriptive names**: `STRIPE_SECRET_KEY` is clearer than `KEY_1`.\n- **Rotate credentials regularly**: Update secrets in the manager, then re-publish.\n- **One secret per variable**: Avoid concatenating multiple keys into a single environment variable.\n- **Test after publish**: Confirm your app can read the secret by checking logs or a health endpoint.\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"The chat-to-published app flow\" icon=\"messages\" href=\"/the-chat-to-published app-flow\">\nUnderstand how build and publish phases handle credentials\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nConfigure your MongoDB connection string as a secret\n</Card>\n\n<Card title=\"The Universal LLM Key\" icon=\"key\" href=\"/the-universal-llm-key\">\nLearn how agents access LLMs during the build phase\n</Card>\n\n<Card title=\"App slow, crashing or cold-starting\" icon=\"triangle-alert\" href=\"/app-slow-crashing-or-cold-starting\">\nTroubleshoot runtime issues, including missing secrets\n</Card>\n</CardGroup>","published_title":"Secrets & env variables","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"98829235-10fc-4c57-8bd3-e15514014abd","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing types","slug":"deployment-types","content":"## Overview\n\nEmergent has two publish environments, **preview** and **production**, that serve distinct purposes in your development workflow. Understanding how they differ helps you test confidently and release intentionally.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n## The two publish environments\n\n<CardGroup cols={2}>\n<Card title=\"Preview\" icon=\"eye\">\nYour development sandbox, used for building and iterating with the agent before going live.\n</Card>\n<Card title=\"Production\" icon=\"rocket\">\nThe live, publicly accessible version of your app, published from the Emergent platform.\n</Card>\n</CardGroup>\n\n## Preview environment\n\nThe preview environment is your active development sandbox, the place where the agent builds, edits, and iterates on your app. It is not a snapshot or a permanent artifact; it is a single, mutable workspace.\n\n**Key characteristics:**\n\n- **Single sandbox per project**: there is one preview environment per job, not multiple parallel previews\n- **Preview URL**: accessible at `{slug}.preview.emergentagent.com`\n- **Sleeps after inactivity**: the preview spins down after **30 minutes** of inactivity to conserve resources\n- **Separate environment variables**: preview env vars are independent from production after the first publish (the first publish carries `.env` values across as a one-time seed). You can add .env keys, which will merge on re-publish but not the values of the keys.\n- **Rollback in preview**: you can roll back the conversation and code in preview using the Rollback button in the chat timeline; re-publish to push any changes to production\n\n**When to use preview:**\n\n- Building and iterating with the agent\n- Testing new features before releasing to users\n- Reviewing changes before hitting **Publish** or **Re-publish**\n\n<Note>\nBecause preview sleeps after 30 minutes, it may take a moment to wake when you return. This is expected behaviour and does not affect your production published app.\n</Note>\n\n## Production environment\n\nProduction is the live version of your app, the URL your end users visit. You create or update it by clicking **Publish** (first time) or **Re-publish** (subsequent updates) from the platform.\n\n**Key characteristics:**\n\n- **Production URL**: your app is served at `<appname>.emergent.host` (or a [custom domain](/custom-domain))\n- **Stays live**: production does not sleep the way preview does\n- **Separate environment variables**: production secrets are managed independently from preview; edit them in **Preview → Manage → Secrets**\n- **Default subdomain cannot be renamed**: once set, the subdomain is permanent; deleted URLs are never reused\n\n**Published app operations available in production:**\n\n- **Re-publish**: update the same app with the latest code\n- **Replace**: zero-downtime blue-green swap of a different job onto a live app (user secrets carried over; choose to keep or start a fresh DB)\n\n- **Rollback**: revert to one of up to **3** previous production images (URL and database remain unchanged)\n\n<Tip>\nThere is no \"Promote to Production\" flow. You simply iterate in preview and click **Re-publish** when you are ready to ship. Republishes are free of charge (beyond the monthly tier fee). \n</Tip>\n\n## Comparison table\n\n| Aspect | Preview | Production |\n|--------|---------|------------|\n| **URL** | `{slug}.preview.emergentagent.com` | `<appname>.emergent.host` (or custom domain) |\n| **Sleep behaviour** | Sleeps after 30 min inactivity | Always live |\n| **Environment variables** | Separate from production (seeded from `.env` on first publish) | Separate from preview; managed in **Preview → Manage → Secrets** |\n| **Typical use** | Building, iterating, testing | Live release to end users |\n\n| **Rollback** | Chat/code rollback via timeline button | Up to 3 previous production images |\n\n## Environment variables and secrets\n\nPreview and production environment variable sets are **completely separate**. Changes you make to secrets in one environment do not automatically carry over to the other. The one exception is if you are adding a brand new key for a new integration. The secret values for the key still has to be set in the secrets panel.\n\n- **In preview**: env vars live in `.env` files inside the app code; the agent reads and writes them directly\n- **In production**: secrets are managed in **Preview → Manage → Secrets**; the UI can edit values of existing keys but cannot add or delete keys (to add a new key, ask the agent to add it to `.env`, then re-publish)\n\n<Warning>\nNever paste real API keys into the chat. Chat content is sent to the AI provider. Enter real third-party keys in **Preview → Manage → Secrets → Custom keys** instead.\n</Warning>\n\n## Publishing plan considerations\n\nPublishing tiers, **Starter, Launch, Grow, Scale, Elite**, determine the CPU, and RAM for your production app. The minimum to start a published app is **50 credits**. Tier changes take approximately 2 minutes and do not require a rebuild.\n\nFor more detail on resource allocation per tier, see [Publishing plan levels](/deployment-plan-levels).\n\nIf you encounter problems during published app, consult the [publishing issues](/deployment-issues) and [publishing pipeline failures](/deployment-pipeline-failures) troubleshooting guides.\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"The chat-to-published app flow\" icon=\"comments\" href=\"/the-chat-to-published app-flow\">\nSee how your app goes from a chat prompt to a live published app.\n</Card>\n<Card title=\"Publishing plan levels\" icon=\"layer-group\" href=\"/published app-plan-levels\">\nCompare resource allocations across Starter, Launch, Grow, Scale, and Elite tiers.\n</Card>\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nConfigure a custom domain for your production published app.\n</Card>\n<Card title=\"Publishing issues\" icon=\"triangle-exclamation\" href=\"/published app-issues\">\nTroubleshoot common published app errors and failures.\n</Card>\n</CardGroup>","order":22,"parent_id":null,"icon":"rocket","description":"The different deployment types available and when each applies.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:07:38.884519+00:00","published_at":"2026-10-05T14:07:38.884519+00:00","published_content":"## Overview\n\nEmergent has two publish environments, **preview** and **production**, that serve distinct purposes in your development workflow. Understanding how they differ helps you test confidently and release intentionally.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n## The two publish environments\n\n<CardGroup cols={2}>\n<Card title=\"Preview\" icon=\"eye\">\nYour development sandbox, used for building and iterating with the agent before going live.\n</Card>\n<Card title=\"Production\" icon=\"rocket\">\nThe live, publicly accessible version of your app, published from the Emergent platform.\n</Card>\n</CardGroup>\n\n## Preview environment\n\nThe preview environment is your active development sandbox, the place where the agent builds, edits, and iterates on your app. It is not a snapshot or a permanent artifact; it is a single, mutable workspace.\n\n**Key characteristics:**\n\n- **Single sandbox per project**: there is one preview environment per job, not multiple parallel previews\n- **Preview URL**: accessible at `{slug}.preview.emergentagent.com`\n- **Sleeps after inactivity**: the preview spins down after **30 minutes** of inactivity to conserve resources\n- **Separate environment variables**: preview env vars are independent from production after the first publish (the first publish carries `.env` values across as a one-time seed). You can add .env keys, which will merge on re-publish but not the values of the keys.\n- **Rollback in preview**: you can roll back the conversation and code in preview using the Rollback button in the chat timeline; re-publish to push any changes to production\n\n**When to use preview:**\n\n- Building and iterating with the agent\n- Testing new features before releasing to users\n- Reviewing changes before hitting **Publish** or **Re-publish**\n\n<Note>\nBecause preview sleeps after 30 minutes, it may take a moment to wake when you return. This is expected behaviour and does not affect your production published app.\n</Note>\n\n## Production environment\n\nProduction is the live version of your app, the URL your end users visit. You create or update it by clicking **Publish** (first time) or **Re-publish** (subsequent updates) from the platform.\n\n**Key characteristics:**\n\n- **Production URL**: your app is served at `<appname>.emergent.host` (or a [custom domain](/custom-domain))\n- **Stays live**: production does not sleep the way preview does\n- **Separate environment variables**: production secrets are managed independently from preview; edit them in **Preview → Manage → Secrets**\n- **Default subdomain cannot be renamed**: once set, the subdomain is permanent; deleted URLs are never reused\n\n**Published app operations available in production:**\n\n- **Re-publish**: update the same app with the latest code\n- **Replace**: zero-downtime blue-green swap of a different job onto a live app (user secrets carried over; choose to keep or start a fresh DB)\n\n- **Rollback**: revert to one of up to **3** previous production images (URL and database remain unchanged)\n\n<Tip>\nThere is no \"Promote to Production\" flow. You simply iterate in preview and click **Re-publish** when you are ready to ship. Republishes are free of charge (beyond the monthly tier fee). \n</Tip>\n\n## Comparison table\n\n| Aspect | Preview | Production |\n|--------|---------|------------|\n| **URL** | `{slug}.preview.emergentagent.com` | `<appname>.emergent.host` (or custom domain) |\n| **Sleep behaviour** | Sleeps after 30 min inactivity | Always live |\n| **Environment variables** | Separate from production (seeded from `.env` on first publish) | Separate from preview; managed in **Preview → Manage → Secrets** |\n| **Typical use** | Building, iterating, testing | Live release to end users |\n\n| **Rollback** | Chat/code rollback via timeline button | Up to 3 previous production images |\n\n## Environment variables and secrets\n\nPreview and production environment variable sets are **completely separate**. Changes you make to secrets in one environment do not automatically carry over to the other. The one exception is if you are adding a brand new key for a new integration. The secret values for the key still has to be set in the secrets panel.\n\n- **In preview**: env vars live in `.env` files inside the app code; the agent reads and writes them directly\n- **In production**: secrets are managed in **Preview → Manage → Secrets**; the UI can edit values of existing keys but cannot add or delete keys (to add a new key, ask the agent to add it to `.env`, then re-publish)\n\n<Warning>\nNever paste real API keys into the chat. Chat content is sent to the AI provider. Enter real third-party keys in **Preview → Manage → Secrets → Custom keys** instead.\n</Warning>\n\n## Publishing plan considerations\n\nPublishing tiers, **Starter, Launch, Grow, Scale, Elite**, determine the CPU, and RAM for your production app. The minimum to start a published app is **50 credits**. Tier changes take approximately 2 minutes and do not require a rebuild.\n\nFor more detail on resource allocation per tier, see [Publishing plan levels](/deployment-plan-levels).\n\nIf you encounter problems during published app, consult the [publishing issues](/deployment-issues) and [publishing pipeline failures](/deployment-pipeline-failures) troubleshooting guides.\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"The chat-to-published app flow\" icon=\"comments\" href=\"/the-chat-to-published app-flow\">\nSee how your app goes from a chat prompt to a live published app.\n</Card>\n<Card title=\"Publishing plan levels\" icon=\"layer-group\" href=\"/published app-plan-levels\">\nCompare resource allocations across Starter, Launch, Grow, Scale, and Elite tiers.\n</Card>\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nConfigure a custom domain for your production published app.\n</Card>\n<Card title=\"Publishing issues\" icon=\"triangle-exclamation\" href=\"/published app-issues\">\nTroubleshoot common published app errors and failures.\n</Card>\n</CardGroup>","published_title":"Publishing types","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"f475d182-d4a6-468a-ae27-24c672f1c91c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Database (MongoDB)","slug":"database-mongodb","content":"## Where your database lives\n\nEmergent apps use **MongoDB** to store your data. The basics:\n\n- Your database lives on a **shared cluster** managed by Emergent: you don't need to provision or configure anything.\n- If you need isolation, you can opt for a **Dedicated Database** (a paid upgrade).\n- To check and validate your data, use the **Database Viewer** tool.\n\n<Info>\nMongoDB runs on Emergent's managed cloud by default. You can also bring your own database (MongoDB Atlas, self-hosted, etc.): see [Migrating to your own database](#migrating-to-your-own-database) below.\n</Info>\n\n---\n\n## Preview vs Production database\n\n<Warning title=\"Separate databases - data does not auto-sync\">\n**Preview** (the workspace) and **Production** (the published app at `yourapp.emergent.host`) use separate MongoDB databases. Changes you make in preview - new collections, documents, schema updates - do **not** automatically flow to production.\n</Warning>\n\nThis is a common gotcha: you might add test data in preview, then publish and wonder where it went. On first publish, Emergent migrates your preview data to the production Atlas instance. After that, the two databases are managed independently.\n\nFor more context on the preview/production split, see [Preview vs Published](/preview-vs-deployed-separate).\n\n---\n\n## Database behavior on re-publish vs replace\n\nWhen you push a new published app, Emergent offers two options:\n\n<Columns cols={2}>\n<Card title=\"Re-publish\" icon=\"rotate-cw\">\nUpdates code and dependencies but **keeps the existing production database** unchanged. Use this for most updates.\n</Card>\n\n<Card title=\"Replace\" icon=\"refresh-ccw\">\nPerforms a blue-green swap across two jobs: a new job is forked, traffic switches over to it, and the old job is then torn down. You choose whether to:\n- Keep the existing production DB, or\n- Start with a **fresh copy** of the preview database (useful for schema changes or resetting data).\n</Card>\n</Columns>\n\n<Tip>\nIf you've made schema changes or want to seed production with preview data, use **Replace** and select \"Copy preview database to production.\"\n</Tip>\n\n---\n\n## Inspecting & exporting your database\n\nEmergent provides two ways to browse and export your data:\n\n### Database Manager (web UI)\n\nThe built-in **Database Manager** lets you browse collections and documents in both preview and production databases:\n\n<Steps>\n<Step title=\"Open the Database Manager\">\nOpen the Database Manager from inside Emergent (direct URL access to mongoview.emergent.host does not work, it must be launched from within the platform).\n</Step>\n\n<Step title=\"Select your environment\">\nChoose **Preview** or **Production** from the environment switcher in the top bar.\n</Step>\n\n<Step title=\"Browse collections\">\nClick any collection to view documents. You can filter, sort, and inspect individual records.\n</Step>\n</Steps>\n\n<Note>\nThe Database Manager allows you to view, edit, and delete live data in production databases. Use caution, edits to production data are immediate and cannot be undone.\n</Note>\n\n### Exporting the preview database (mongodump)\n\nYou can export your preview database as a `.bson` dump file using `mongodump` directly in the workspace VS Code terminal:\n\n<Steps>\n<Step title=\"Open the terminal\">\nIn the VS Code workspace, press `` Ctrl+` `` (or `Cmd+` on Mac) to open the integrated terminal.\n</Step>\n\n<Step title=\"Run mongodump\">\n```bash\nmongodump --uri=\"$MONGO_URL\" --out=./dump\n```\nThis creates a `./dump` folder with `.bson` files for each collection.\n</Step>\n\n<Step title=\"Download the dump\">\nRight-click the `dump` folder in the VS Code file explorer and select **Download**. The folder will be zipped and saved to your local machine.\n</Step>\n</Steps>\n\n<Tip>\nUse `mongorestore` locally to import the dump into your own MongoDB instance for offline development or backup.\n</Tip>\n\n---\n\n## Migrating to your own database\n\nMost apps run successfully on the Emergent-managed database indefinitely: it is included in your subscription and scales automatically. Migrating to your own external MongoDB is optional, available for **published apps only**, and typically reserved for apps that need:\n\n- **Advanced control** over backups, retention policies, or access patterns\n- **Production scale** with dedicated resources or performance SLAs\n- **Compliance** with a specific cloud region or provider\n- **Data consolidation** across multiple services in your own infrastructure\n- **Full ownership of the database layer**, for example if you plan to take your app outside Emergent\n\n<Warning>\nMigration is a **manual runbook**. There is no automatic copy, sync, or zero-downtime cutover - you perform each step yourself, then re-publish to switch over. There is also no guaranteed rollback to the managed database afterwards, so test your external database thoroughly and keep a verified export of your data on hand.\n</Warning>\n\n<Steps>\n<Step title=\"Export your data\">\nExport your existing data using the methods in [Inspecting & exporting your database](#inspecting-exporting-your-database) above. Note that the managed **production** cluster does not accept direct external connections - use the Database Manager, or contact support at support@emergent.sh for help with a production export.\n</Step>\n\n<Step title=\"Provision your own MongoDB\">\nSet up a MongoDB instance with your preferred provider (MongoDB Atlas is recommended), reachable from the internet with appropriate network rules. You'll need a connection string in the standard format:\n\n```\nmongodb+srv://username:password@cluster.provider.net/database_name\n```\n</Step>\n\n<Step title=\"Import your data\">\nImport the export from Step 1 into your new instance using `mongorestore` or your provider's import tooling. Verify the import is complete before proceeding.\n</Step>\n\n<Step title=\"Allowlist Emergent's egress IPs\">\nAdd Emergent's egress IP addresses to your database's network access list so your app can connect. The current list is at **app.emergent.sh/ip-addresses**.\n</Step>\n\n<Step title=\"Update MONGO_URL in your System keys\">\nGo to **Preview → Manage → Secrets**, find **`MONGO_URL`** under System keys, and update its value to your new connection string. Update **`DB_NAME`** too if your new database uses a different name.\n\n<Note>\nThe platform key is **`MONGO_URL`**, not `DATABASE_URL` or `MONGODB_URI`. Using the wrong key name will not be auto-detected by the platform.\n</Note>\n</Step>\n\n<Step title=\"Re-publish your app\">\nRe-publish your app. Re-publishing is free of charge (beyond the monthly tier fee). \n\nAfter the re-publish completes, your app connects to your external database.\n</Step>\n</Steps>\n\nAfter migration:\n\n- You are responsible for backups, monitoring, and scaling - the Emergent-managed database scales automatically; your own database does not, so ensure it has sufficient resources and connection limits for your app's workload.\n- Emergent continues to publish, build, and serve your app normally.\n- The Emergent-managed database is no longer actively used by your app.\n\nFor help at any step, contact support at support@emergent.sh or use the in-app live chat.\n\n---\n\n## Related topics\n\n<CardGroup cols={2}>\n<Card title=\"File storage (Emergent Object Store)\" icon=\"folder-open\" href=\"/file-storage-emergent-object-store\">\nHow to store and serve user uploads, images, and other files\n</Card>\n\n<Card title=\"Database & data on mobile\" icon=\"smartphone\" href=\"/database-data-on-mobile\">\nSpecial considerations for mobile apps\n</Card>\n\n<Card title=\"Your data & ownership\" icon=\"shield-check\" href=\"/your-data-ownership\">\nWho owns your data and how to export it\n</Card>\n\n<Card title=\"Preview vs Published\" icon=\"git-branch\" href=\"/preview-vs-deployed-separate\">\nHow the preview and production environments relate\n</Card>\n</CardGroup>\n","order":23,"parent_id":null,"icon":"database","description":"Your app's database is a MongoDB connection string (a URL), not a file.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:07:38.728719+00:00","published_at":"2026-10-05T14:07:38.728719+00:00","published_content":"## Where your database lives\n\nEmergent apps use **MongoDB** to store your data. The basics:\n\n- Your database lives on a **shared cluster** managed by Emergent: you don't need to provision or configure anything.\n- If you need isolation, you can opt for a **Dedicated Database** (a paid upgrade).\n- To check and validate your data, use the **Database Viewer** tool.\n\n<Info>\nMongoDB runs on Emergent's managed cloud by default. You can also bring your own database (MongoDB Atlas, self-hosted, etc.): see [Migrating to your own database](#migrating-to-your-own-database) below.\n</Info>\n\n---\n\n## Preview vs Production database\n\n<Warning title=\"Separate databases - data does not auto-sync\">\n**Preview** (the workspace) and **Production** (the published app at `yourapp.emergent.host`) use separate MongoDB databases. Changes you make in preview - new collections, documents, schema updates - do **not** automatically flow to production.\n</Warning>\n\nThis is a common gotcha: you might add test data in preview, then publish and wonder where it went. On first publish, Emergent migrates your preview data to the production Atlas instance. After that, the two databases are managed independently.\n\nFor more context on the preview/production split, see [Preview vs Published](/preview-vs-deployed-separate).\n\n---\n\n## Database behavior on re-publish vs replace\n\nWhen you push a new published app, Emergent offers two options:\n\n<Columns cols={2}>\n<Card title=\"Re-publish\" icon=\"rotate-cw\">\nUpdates code and dependencies but **keeps the existing production database** unchanged. Use this for most updates.\n</Card>\n\n<Card title=\"Replace\" icon=\"refresh-ccw\">\nPerforms a blue-green swap across two jobs: a new job is forked, traffic switches over to it, and the old job is then torn down. You choose whether to:\n- Keep the existing production DB, or\n- Start with a **fresh copy** of the preview database (useful for schema changes or resetting data).\n</Card>\n</Columns>\n\n<Tip>\nIf you've made schema changes or want to seed production with preview data, use **Replace** and select \"Copy preview database to production.\"\n</Tip>\n\n---\n\n## Inspecting & exporting your database\n\nEmergent provides two ways to browse and export your data:\n\n### Database Manager (web UI)\n\nThe built-in **Database Manager** lets you browse collections and documents in both preview and production databases:\n\n<Steps>\n<Step title=\"Open the Database Manager\">\nOpen the Database Manager from inside Emergent (direct URL access to mongoview.emergent.host does not work, it must be launched from within the platform).\n</Step>\n\n<Step title=\"Select your environment\">\nChoose **Preview** or **Production** from the environment switcher in the top bar.\n</Step>\n\n<Step title=\"Browse collections\">\nClick any collection to view documents. You can filter, sort, and inspect individual records.\n</Step>\n</Steps>\n\n<Note>\nThe Database Manager allows you to view, edit, and delete live data in production databases. Use caution, edits to production data are immediate and cannot be undone.\n</Note>\n\n### Exporting the preview database (mongodump)\n\nYou can export your preview database as a `.bson` dump file using `mongodump` directly in the workspace VS Code terminal:\n\n<Steps>\n<Step title=\"Open the terminal\">\nIn the VS Code workspace, press `` Ctrl+` `` (or `Cmd+` on Mac) to open the integrated terminal.\n</Step>\n\n<Step title=\"Run mongodump\">\n```bash\nmongodump --uri=\"$MONGO_URL\" --out=./dump\n```\nThis creates a `./dump` folder with `.bson` files for each collection.\n</Step>\n\n<Step title=\"Download the dump\">\nRight-click the `dump` folder in the VS Code file explorer and select **Download**. The folder will be zipped and saved to your local machine.\n</Step>\n</Steps>\n\n<Tip>\nUse `mongorestore` locally to import the dump into your own MongoDB instance for offline development or backup.\n</Tip>\n\n---\n\n## Migrating to your own database\n\nMost apps run successfully on the Emergent-managed database indefinitely: it is included in your subscription and scales automatically. Migrating to your own external MongoDB is optional, available for **published apps only**, and typically reserved for apps that need:\n\n- **Advanced control** over backups, retention policies, or access patterns\n- **Production scale** with dedicated resources or performance SLAs\n- **Compliance** with a specific cloud region or provider\n- **Data consolidation** across multiple services in your own infrastructure\n- **Full ownership of the database layer**, for example if you plan to take your app outside Emergent\n\n<Warning>\nMigration is a **manual runbook**. There is no automatic copy, sync, or zero-downtime cutover - you perform each step yourself, then re-publish to switch over. There is also no guaranteed rollback to the managed database afterwards, so test your external database thoroughly and keep a verified export of your data on hand.\n</Warning>\n\n<Steps>\n<Step title=\"Export your data\">\nExport your existing data using the methods in [Inspecting & exporting your database](#inspecting-exporting-your-database) above. Note that the managed **production** cluster does not accept direct external connections - use the Database Manager, or contact support at support@emergent.sh for help with a production export.\n</Step>\n\n<Step title=\"Provision your own MongoDB\">\nSet up a MongoDB instance with your preferred provider (MongoDB Atlas is recommended), reachable from the internet with appropriate network rules. You'll need a connection string in the standard format:\n\n```\nmongodb+srv://username:password@cluster.provider.net/database_name\n```\n</Step>\n\n<Step title=\"Import your data\">\nImport the export from Step 1 into your new instance using `mongorestore` or your provider's import tooling. Verify the import is complete before proceeding.\n</Step>\n\n<Step title=\"Allowlist Emergent's egress IPs\">\nAdd Emergent's egress IP addresses to your database's network access list so your app can connect. The current list is at **app.emergent.sh/ip-addresses**.\n</Step>\n\n<Step title=\"Update MONGO_URL in your System keys\">\nGo to **Preview → Manage → Secrets**, find **`MONGO_URL`** under System keys, and update its value to your new connection string. Update **`DB_NAME`** too if your new database uses a different name.\n\n<Note>\nThe platform key is **`MONGO_URL`**, not `DATABASE_URL` or `MONGODB_URI`. Using the wrong key name will not be auto-detected by the platform.\n</Note>\n</Step>\n\n<Step title=\"Re-publish your app\">\nRe-publish your app. Re-publishing is free of charge (beyond the monthly tier fee). \n\nAfter the re-publish completes, your app connects to your external database.\n</Step>\n</Steps>\n\nAfter migration:\n\n- You are responsible for backups, monitoring, and scaling - the Emergent-managed database scales automatically; your own database does not, so ensure it has sufficient resources and connection limits for your app's workload.\n- Emergent continues to publish, build, and serve your app normally.\n- The Emergent-managed database is no longer actively used by your app.\n\nFor help at any step, contact support at support@emergent.sh or use the in-app live chat.\n\n---\n\n## Related topics\n\n<CardGroup cols={2}>\n<Card title=\"File storage (Emergent Object Store)\" icon=\"folder-open\" href=\"/file-storage-emergent-object-store\">\nHow to store and serve user uploads, images, and other files\n</Card>\n\n<Card title=\"Database & data on mobile\" icon=\"smartphone\" href=\"/database-data-on-mobile\">\nSpecial considerations for mobile apps\n</Card>\n\n<Card title=\"Your data & ownership\" icon=\"shield-check\" href=\"/your-data-ownership\">\nWho owns your data and how to export it\n</Card>\n\n<Card title=\"Preview vs Published\" icon=\"git-branch\" href=\"/preview-vs-deployed-separate\">\nHow the preview and production environments relate\n</Card>\n</CardGroup>\n","published_title":"Database (MongoDB)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"063dfef3-68d4-46be-b64c-c2c76150241b","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing plan levels","slug":"deployment-plan-levels","content":"## Overview\n\nEvery published app on Emergent runs on a **publishing tier**, a CPU and memory allocation that determines the compute resources available to your application. Choosing the right tier ensures your app has enough headroom to handle its workload without over-provisioning.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nTiers range from light (suitable for low-traffic services and prototypes) to heavy (for compute-intensive backends and high-concurrency APIs).\n\n---\n\n## Available publishing tiers\n\nEmergent offers five tiers, each billed as a fixed monthly credit fee:\n\n| Tier | Credits/month | CPU | Memory | Typical use cases |\n|------------|--------------|------------|--------|------------------------------------------------------|\n| **Starter** | 50 | 0.05 vCPU | 200 MB | Prototypes, low-traffic APIs, internal tools |\n| **Launch** | 125 | 0.5 vCPU | 2 GB | Small production apps, hobby projects |\n| **Grow** | 225 | 1 vCPU | 4 GB | Production web apps, moderate concurrency |\n| **Scale** | 450 | 2 vCPU | 8 GB | High-traffic services, background workers |\n| **Elite** | 1,100 | 4 vCPU | 16 GB | Compute-intensive workloads, ML inference |\n\n<Note>\nTier fees are charged as a **fixed monthly credit amount**, not per hour of uptime. The minimum to start a published app is 50 credits. Full per-tier specs: Starter 0.05 vCPU / 200 MB, Launch 0.5 vCPU / 2 GB, Grow 1 vCPU / 4 GB, Scale 2 vCPU / 8 GB, Elite 4 vCPU / 16 GB.\n</Note>\n\n---\n\n## How to choose the right tier\n\n### Start with your app's workload\n\nAsk yourself:\n\n- **Traffic volume**: How many concurrent users or requests per second do you expect?\n- **Data processing**: Does the app handle large files, images, or compute-heavy operations?\n- **Background jobs**: Do you run scheduled tasks, email sends, or queue workers?\n- **Dependencies**: Do your runtime libraries (Python packages, Node modules) have high memory overhead?\n\n<Tip title=\"Start small, scale up\">\nIf you're unsure, begin on **Starter** or **Launch** and upgrade as needed. You can change your tier anytime from the publishing settings.\n</Tip>\n\n### When to use Starter\n\nChoose **Starter** if your app:\n\n- Is a **prototype or proof-of-concept** with minimal traffic\n- Runs a very lightweight backend or internal tool\n- Expects very low concurrency\n\n<Warning>\nStarter is tightly resource-constrained (0.05 vCPU / 200 MB). It is not suitable for production apps under meaningful load. Upgrade to Launch or higher for anything beyond minimal usage.\n</Warning>\n\n### When to use Launch\n\nChoose **Launch** if your app:\n\n- Is a **lightweight REST API** or simple web server\n- Handles **low-to-moderate traffic**\n- Is a hobby project or early-stage product\n\n### When to use Grow\n\nChoose **Grow** if your app:\n\n- Serves a **production web application** with moderate concurrency\n- Processes form submissions, image uploads, or external API calls\n- Runs a database-backed app with typical query loads\n\nThis is a **common tier for growing production services**.\n\n### When to use Scale\n\nChoose **Scale** if your app:\n\n- Handles **higher traffic** or more demanding workloads\n- Needs meaningfully more CPU (2 vCPU) and memory (8 GB)\n- Runs background workers or queue consumers alongside the main service\n\n### When to use Elite\n\nChoose **Elite** if your app:\n\n- Has **the most demanding compute or memory requirements**\n- Runs ML inference, video processing, or large data transformations\n- Requires maximum available resources on the platform\n\n---\n\n## Changing your tier\n\n<Steps>\n<Step title=\"Open your published app\">\nNavigate to your app's **Manage Publishing** panel and select the active published app.\n</Step>\n\n<Step title=\"Check resource allocation\">\nGo to the **Resources** tab to see your current tier's allocated CPU and memory.\n\nReal-time CPU and memory usage graphs are not currently available in the Resources tab, it shows your tier's allocation only.\n</Step>\n\n<Step title=\"Change tier if needed\">\nClick **Change Plan** and select a higher or lower tier. A tier change triggers a no-build re-publish that takes approximately 2 minutes. The change is free of charge (beyond the monthly tier fee).\n\n</Step>\n</Steps>\n\n<Info>\nBoth upgrades and downgrades are supported. If your app is over-provisioned, you can scale down to a lower tier to reduce your monthly credit spend.\n</Info>\n\n---\n\n## Pricing and credits\n\nEach tier costs a **fixed number of credits per month**, not per hour of uptime. Higher tiers cost more per month but provide greater CPU and memory allocations.\n\n| Tier | Credits/month |\n|-------------|--------------|\n| Starter | 50 |\n\n| Launch | 125 |\n\n| Grow | 225 |\n\n| Scale | 450 |\n| Elite | 1,100 |\n\nA minimum of **50 credits** is required to start any published app. Visit the **Billing** section in your workspace or see [Managing credit usage](/managing-credit-usage) for full details on credit balances and top-ups.","order":24,"parent_id":null,"icon":"rocket","description":"1. What the plan levels are: CPU/memory tiers.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:07:38.765470+00:00","published_at":"2026-10-05T14:07:38.765470+00:00","published_content":"## Overview\n\nEvery published app on Emergent runs on a **publishing tier**, a CPU and memory allocation that determines the compute resources available to your application. Choosing the right tier ensures your app has enough headroom to handle its workload without over-provisioning.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nTiers range from light (suitable for low-traffic services and prototypes) to heavy (for compute-intensive backends and high-concurrency APIs).\n\n---\n\n## Available publishing tiers\n\nEmergent offers five tiers, each billed as a fixed monthly credit fee:\n\n| Tier | Credits/month | CPU | Memory | Typical use cases |\n|------------|--------------|------------|--------|------------------------------------------------------|\n| **Starter** | 50 | 0.05 vCPU | 200 MB | Prototypes, low-traffic APIs, internal tools |\n| **Launch** | 125 | 0.5 vCPU | 2 GB | Small production apps, hobby projects |\n| **Grow** | 225 | 1 vCPU | 4 GB | Production web apps, moderate concurrency |\n| **Scale** | 450 | 2 vCPU | 8 GB | High-traffic services, background workers |\n| **Elite** | 1,100 | 4 vCPU | 16 GB | Compute-intensive workloads, ML inference |\n\n<Note>\nTier fees are charged as a **fixed monthly credit amount**, not per hour of uptime. The minimum to start a published app is 50 credits. Full per-tier specs: Starter 0.05 vCPU / 200 MB, Launch 0.5 vCPU / 2 GB, Grow 1 vCPU / 4 GB, Scale 2 vCPU / 8 GB, Elite 4 vCPU / 16 GB.\n</Note>\n\n---\n\n## How to choose the right tier\n\n### Start with your app's workload\n\nAsk yourself:\n\n- **Traffic volume**: How many concurrent users or requests per second do you expect?\n- **Data processing**: Does the app handle large files, images, or compute-heavy operations?\n- **Background jobs**: Do you run scheduled tasks, email sends, or queue workers?\n- **Dependencies**: Do your runtime libraries (Python packages, Node modules) have high memory overhead?\n\n<Tip title=\"Start small, scale up\">\nIf you're unsure, begin on **Starter** or **Launch** and upgrade as needed. You can change your tier anytime from the publishing settings.\n</Tip>\n\n### When to use Starter\n\nChoose **Starter** if your app:\n\n- Is a **prototype or proof-of-concept** with minimal traffic\n- Runs a very lightweight backend or internal tool\n- Expects very low concurrency\n\n<Warning>\nStarter is tightly resource-constrained (0.05 vCPU / 200 MB). It is not suitable for production apps under meaningful load. Upgrade to Launch or higher for anything beyond minimal usage.\n</Warning>\n\n### When to use Launch\n\nChoose **Launch** if your app:\n\n- Is a **lightweight REST API** or simple web server\n- Handles **low-to-moderate traffic**\n- Is a hobby project or early-stage product\n\n### When to use Grow\n\nChoose **Grow** if your app:\n\n- Serves a **production web application** with moderate concurrency\n- Processes form submissions, image uploads, or external API calls\n- Runs a database-backed app with typical query loads\n\nThis is a **common tier for growing production services**.\n\n### When to use Scale\n\nChoose **Scale** if your app:\n\n- Handles **higher traffic** or more demanding workloads\n- Needs meaningfully more CPU (2 vCPU) and memory (8 GB)\n- Runs background workers or queue consumers alongside the main service\n\n### When to use Elite\n\nChoose **Elite** if your app:\n\n- Has **the most demanding compute or memory requirements**\n- Runs ML inference, video processing, or large data transformations\n- Requires maximum available resources on the platform\n\n---\n\n## Changing your tier\n\n<Steps>\n<Step title=\"Open your published app\">\nNavigate to your app's **Manage Publishing** panel and select the active published app.\n</Step>\n\n<Step title=\"Check resource allocation\">\nGo to the **Resources** tab to see your current tier's allocated CPU and memory.\n\nReal-time CPU and memory usage graphs are not currently available in the Resources tab, it shows your tier's allocation only.\n</Step>\n\n<Step title=\"Change tier if needed\">\nClick **Change Plan** and select a higher or lower tier. A tier change triggers a no-build re-publish that takes approximately 2 minutes. The change is free of charge (beyond the monthly tier fee).\n\n</Step>\n</Steps>\n\n<Info>\nBoth upgrades and downgrades are supported. If your app is over-provisioned, you can scale down to a lower tier to reduce your monthly credit spend.\n</Info>\n\n---\n\n## Pricing and credits\n\nEach tier costs a **fixed number of credits per month**, not per hour of uptime. Higher tiers cost more per month but provide greater CPU and memory allocations.\n\n| Tier | Credits/month |\n|-------------|--------------|\n| Starter | 50 |\n\n| Launch | 125 |\n\n| Grow | 225 |\n\n| Scale | 450 |\n| Elite | 1,100 |\n\nA minimum of **50 credits** is required to start any published app. Visit the **Billing** section in your workspace or see [Managing credit usage](/managing-credit-usage) for full details on credit balances and top-ups.","published_title":"Publishing plan levels","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"15d3fd47-83e9-4e5b-a134-835ab46c2488","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"File storage (Emergent Object Store)","slug":"file-storage-emergent-object-store","content":"## Overview\n\nEmergent provides **managed object storage** through **Emergent Object Store**. This lets your apps handle user uploads, avatars, documents, images, and other files without connecting an external AWS account or managing storage credentials.\n\nEmergent Object Store is accessed through the **Universal LLM Key**, so no separate storage credentials or configuration are required.\n\n---\n\n## Using Emergent Object Store\n\nThe simplest way to use object storage is through Emergent's managed infrastructure. When you describe a file-handling requirement in chat, such as:\n\n- _\"Let users upload profile pictures\"_\n- _\"Add a document upload form and store PDFs\"_\n- _\"Store user-generated images\"_\n\nEmergent automatically provisions and configures the required object storage for your app.\n\n<Note>\nNo AWS account, bucket creation, access keys, or environment-variable configuration is required. The agent handles the storage setup and wiring automatically.\n</Note>\n\nObject storage works in preview and production and is managed by Emergent through the Universal LLM Key.\n\n---\n\n## Security and access control\n\n- **Private by default** - objects are not publicly readable unless you explicitly generate signed URLs or set public ACLs (discouraged).\n- **Scoped credentials** - each organization's access keys can only interact with that organization's bucket.\n- **No cross-org access** - apps in different organizations cannot read each other's files.\n\n<Tip>\nTo let users download uploads, generate **pre-signed URLs** with a short expiry (e.g., 1 hour). This avoids exposing permanent credentials in the browser. Ask the agent: _\"Generate signed URLs for uploaded files so users can download them securely.\"_\n</Tip>\n\n---\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"Profile avatars\">\n    Store and serve user-uploaded images; resize on upload or on-the-fly.\n</Card>\n<Card title=\"Document uploads\">\n    Accept PDFs, spreadsheets, or text files; parse or index them server-side.\n</Card>\n<Card title=\"Media galleries\">\n    Let users upload photos or videos; list and display thumbnails.\n</Card>\n<Card title=\"Export artifacts\">\n    Generate CSVs, reports, or ZIP archives on the server and store them for async download.\n</Card>\n</CardGroup>\n\n---\n\n## Related resources\n\n<CardGroup cols={2}>\n<Card title=\"Database (MongoDB)\" href=\"/database-mongodb\">\n    Persistent NoSQL database included with every published app.\n</Card>\n<Card title=\"Managing credit usage\" href=\"/managing-credit-usage\">\n    Understand which operations consume credits (storage operations do not).\n</Card>\n</CardGroup>","order":26,"parent_id":null,"icon":"folder-open","description":"S3-compatible file storage powered by Tigris (5GB/org quota, no AWS account) for user uploads; requested via the agent, and storage operations do not consume credits.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.893798+00:00","published_at":"2026-09-22T06:19:16.893798+00:00","published_content":"## Overview\n\nEmergent provides **managed object storage** through **Emergent Object Store**. This lets your apps handle user uploads, avatars, documents, images, and other files without connecting an external AWS account or managing storage credentials.\n\nEmergent Object Store is accessed through the **Universal LLM Key**, so no separate storage credentials or configuration are required.\n\n---\n\n## Using Emergent Object Store\n\nThe simplest way to use object storage is through Emergent's managed infrastructure. When you describe a file-handling requirement in chat, such as:\n\n- _\"Let users upload profile pictures\"_\n- _\"Add a document upload form and store PDFs\"_\n- _\"Store user-generated images\"_\n\nEmergent automatically provisions and configures the required object storage for your app.\n\n<Note>\nNo AWS account, bucket creation, access keys, or environment-variable configuration is required. The agent handles the storage setup and wiring automatically.\n</Note>\n\nObject storage works in preview and production and is managed by Emergent through the Universal LLM Key.\n\n---\n\n## Security and access control\n\n- **Private by default** - objects are not publicly readable unless you explicitly generate signed URLs or set public ACLs (discouraged).\n- **Scoped credentials** - each organization's access keys can only interact with that organization's bucket.\n- **No cross-org access** - apps in different organizations cannot read each other's files.\n\n<Tip>\nTo let users download uploads, generate **pre-signed URLs** with a short expiry (e.g., 1 hour). This avoids exposing permanent credentials in the browser. Ask the agent: _\"Generate signed URLs for uploaded files so users can download them securely.\"_\n</Tip>\n\n---\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"Profile avatars\">\n    Store and serve user-uploaded images; resize on upload or on-the-fly.\n</Card>\n<Card title=\"Document uploads\">\n    Accept PDFs, spreadsheets, or text files; parse or index them server-side.\n</Card>\n<Card title=\"Media galleries\">\n    Let users upload photos or videos; list and display thumbnails.\n</Card>\n<Card title=\"Export artifacts\">\n    Generate CSVs, reports, or ZIP archives on the server and store them for async download.\n</Card>\n</CardGroup>\n\n---\n\n## Related resources\n\n<CardGroup cols={2}>\n<Card title=\"Database (MongoDB)\" href=\"/database-mongodb\">\n    Persistent NoSQL database included with every published app.\n</Card>\n<Card title=\"Managing credit usage\" href=\"/managing-credit-usage\">\n    Understand which operations consume credits (storage operations do not).\n</Card>\n</CardGroup>","published_title":"File storage (Emergent Object Store)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"8fb6647c-97fd-4e1a-8457-c40e6323cbfa","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing your web app","slug":"deploying-web","content":"## What published app does\n\nWhen you publish an app in Emergent, the platform provisions production infrastructure and makes your application live at a **public, permanent URL. Unlike the preview environment (which spins up on demand and shuts down after inactivity), a published app runs 24/7** and can handle real user traffic.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nEach published app:\n\n- Creates a stable, shareable URL (e.g. `https://your-app-name.emergent.host`)\n- Provisions serverless compute, storage and any required services\n- Runs health checks and keeps the app online continuously\n- Routes traffic through a CDN for low-latency delivery\n\n<Info title=\"First-time published app\">\nThe first published app of an app can take **~15 minutes** while infrastructure is provisioned and your code is built. Subsequent updates are typically faster.\n</Info>\n\n---\n\n## Cost of a published app\n\nA published app costs **50 credits per month at the Starter tier** (ranging from 50 to 1,100 credits/month depending on your publishing tier) while it remains live. This covers:\n\n- Compute and storage for hosting\n- Network egress and CDN delivery\n- Health monitoring and logging\n- Automatic scaling within platform limits\n\n<Note>\nCredits are deducted **monthly** from your account balance while the app is published. If you shut down the published app, billing stops immediately. See [Managing credit usage](/managing-credit-usage) for details on topping up.\n</Note>\n\n---\n\n## Sharing your published app\n\nOnce published app completes, share the public URL with anyone. No authentication is required unless your app implements its own login flow.\n\n**Common use cases:**\n\n- Share with friends or beta testers for feedback\n- Embed in a portfolio or showcase\n- Connect a custom domain (if supported by your plan)\n- Use in production for low-to-moderate traffic\n\n<Tip>\nThe published URL is permanent as long as the app remains live. You can re-publish updates at any time without changing the URL.\n</Tip>\n\n---\n\n## Shutting down a published app\n\nYou can shut down a published app **at any time** from the workspace. This:\n\n- Stops the app and releases infrastructure\n- Immediately halts the monthly credit charge\n- Preserves your code and project history\n\nTo re-publish later, simply click **Publish** again from the same project.\n\n<Warning>\nShutting down a published app **does not** delete any databases or external services your app may use (e.g. MongoDB). If you want to remove data, manually delete those resources separately. See [Database (MongoDB)](/database-mongodb) for details.\n</Warning>\n\n---\n\n## Monitoring a published app\n\nEmergent provides basic monitoring tools to check the health and performance of your live app.\n\n### Checking uptime\n\nFrom the workspace, the publish status indicator shows:\n\n- **Green (Live)** - app is healthy and responding\n- **Yellow (Degraded)** - partial outage or slow response\n- **Red (Down)** - app is unreachable\n\n<Info>\nThe platform runs automated health checks every few minutes. If your app becomes unresponsive, you'll see a status change in the workspace and may receive an alert (depending on your notification settings).\n</Info>\n\n### Viewing logs\n\nClick **Logs** in the published app panel to stream real-time output from your app. Logs capture:\n\n- HTTP requests and responses\n- Console output (`console.log`, `print`, etc.)\n- Uncaught exceptions and stack traces\n- Framework-level warnings\n\nUse logs to debug unexpected behavior or trace user-reported issues.\n\n### Production errors\n\nIf your app crashes or throws unhandled errors, Emergent surfaces them in the **Errors** tab. Each entry includes:\n\n- Timestamp and affected route or endpoint\n- Full stack trace\n- Request context (URL, headers, user agent)\n\n<Tip title=\"Proactive debugging\">\nCheck the Errors tab regularly, especially after pushing updates. Catching issues early helps maintain a smooth experience for your users.\n</Tip>\n\nFor performance issues (slow load times, cold starts), see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting).\n","order":28,"parent_id":null,"icon":"rocket","description":"1. What deploy does: creates a public URL; production infra live 24/7.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T06:18:22.153118+00:00","published_at":"2026-09-24T06:18:22.153118+00:00","published_content":"## What published app does\n\nWhen you publish an app in Emergent, the platform provisions production infrastructure and makes your application live at a **public, permanent URL. Unlike the preview environment (which spins up on demand and shuts down after inactivity), a published app runs 24/7** and can handle real user traffic.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nEach published app:\n\n- Creates a stable, shareable URL (e.g. `https://your-app-name.emergent.host`)\n- Provisions serverless compute, storage and any required services\n- Runs health checks and keeps the app online continuously\n- Routes traffic through a CDN for low-latency delivery\n\n<Info title=\"First-time published app\">\nThe first published app of an app can take **~15 minutes** while infrastructure is provisioned and your code is built. Subsequent updates are typically faster.\n</Info>\n\n---\n\n## Cost of a published app\n\nA published app costs **50 credits per month at the Starter tier** (ranging from 50 to 1,100 credits/month depending on your publishing tier) while it remains live. This covers:\n\n- Compute and storage for hosting\n- Network egress and CDN delivery\n- Health monitoring and logging\n- Automatic scaling within platform limits\n\n<Note>\nCredits are deducted **monthly** from your account balance while the app is published. If you shut down the published app, billing stops immediately. See [Managing credit usage](/managing-credit-usage) for details on topping up.\n</Note>\n\n---\n\n## Sharing your published app\n\nOnce published app completes, share the public URL with anyone. No authentication is required unless your app implements its own login flow.\n\n**Common use cases:**\n\n- Share with friends or beta testers for feedback\n- Embed in a portfolio or showcase\n- Connect a custom domain (if supported by your plan)\n- Use in production for low-to-moderate traffic\n\n<Tip>\nThe published URL is permanent as long as the app remains live. You can re-publish updates at any time without changing the URL.\n</Tip>\n\n---\n\n## Shutting down a published app\n\nYou can shut down a published app **at any time** from the workspace. This:\n\n- Stops the app and releases infrastructure\n- Immediately halts the monthly credit charge\n- Preserves your code and project history\n\nTo re-publish later, simply click **Publish** again from the same project.\n\n<Warning>\nShutting down a published app **does not** delete any databases or external services your app may use (e.g. MongoDB). If you want to remove data, manually delete those resources separately. See [Database (MongoDB)](/database-mongodb) for details.\n</Warning>\n\n---\n\n## Monitoring a published app\n\nEmergent provides basic monitoring tools to check the health and performance of your live app.\n\n### Checking uptime\n\nFrom the workspace, the publish status indicator shows:\n\n- **Green (Live)** - app is healthy and responding\n- **Yellow (Degraded)** - partial outage or slow response\n- **Red (Down)** - app is unreachable\n\n<Info>\nThe platform runs automated health checks every few minutes. If your app becomes unresponsive, you'll see a status change in the workspace and may receive an alert (depending on your notification settings).\n</Info>\n\n### Viewing logs\n\nClick **Logs** in the published app panel to stream real-time output from your app. Logs capture:\n\n- HTTP requests and responses\n- Console output (`console.log`, `print`, etc.)\n- Uncaught exceptions and stack traces\n- Framework-level warnings\n\nUse logs to debug unexpected behavior or trace user-reported issues.\n\n### Production errors\n\nIf your app crashes or throws unhandled errors, Emergent surfaces them in the **Errors** tab. Each entry includes:\n\n- Timestamp and affected route or endpoint\n- Full stack trace\n- Request context (URL, headers, user agent)\n\n<Tip title=\"Proactive debugging\">\nCheck the Errors tab regularly, especially after pushing updates. Catching issues early helps maintain a smooth experience for your users.\n</Tip>\n\nFor performance issues (slow load times, cold starts), see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting).\n","published_title":"Publishing your web app","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"c0a6b3ac-6f7f-40c7-bb28-f89790b0686d","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Preview vs Published","slug":"preview-vs-deployed-separate","content":"## They are different environments\n\nWhen you build an app in Emergent, you work with **two distinct environments**:\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n- **Preview** - the live sandbox inside the workspace where you test changes as you refine your app with AI agents.\n- **Published** - the production environment serving your real users at your published URL.\n\nEach environment runs with its own URL and server instance. On your **first publish**, Emergent copies your preview's data once into the new production database to seed it; after that the two databases are independent. Later changes you make in preview do not automatically affect the published app until you explicitly push code, and preview edits made after that first publish do **not** sync back into production data.\n\n<Info title=\"Preview is your sandbox\">\nPreview lets you iterate freely, test new features, and fix bugs without risk to your live users. It's the safe place to experiment before committing changes to production.\n</Info>\n\n---\n\n## Why preview changes don't appear live\n\nA common surprise: you've refined your app in preview, the agents have updated the code and tested it successfully - but **none of those changes appear in the published app**.\n\nThis is by design. Emergent keeps the two environments separate so you never accidentally break a live app while iterating. Your published app continues to serve the last version you explicitly pushed, and it will not reflect any preview work until you take action.\n\n<Warning title=\"Changes stay in preview until re-published\">\nEdits, bug fixes, new features and code improvements remain in the preview environment only. To make them live, you must **Re-publish** or **Replace** the published app.\n</Warning>\n\n---\n\n## Re-publish vs Replace\n\nWhen you're ready to push changes from preview to production, Emergent offers two options:\n\n| Action | What it updates | Database impact |\n|--------|----------------|-----------------|\n| **Re-publish** | Code, assets, dependencies | None - keeps existing DB and data |\n| **Replace** | Swaps a different job onto the live app (blue-green) | Keep existing DB or start with a fresh DB |\n\n- Use **Re-publish** when you've only changed UI, logic, styling or dependencies and want to preserve all user data as-is.\n- Use **Replace** when you want to perform a blue-green swap of a different job onto your live app.\n\n---\n\n## Re-publish: push latest code\n\n**Re-publish** copies your preview's code, configuration and assets into a new version alongside the live one and switches traffic at the very end( if it fails, the live app is not affected)- without touching the database.\n\n- The published app's existing MongoDB database remains untouched; all user accounts, records and uploads persist.\n- This is true for every publish **after the first**. Your very first publish seeds the production database once by copying your preview data; from then on the two databases diverge and re-publish never overwrites production data.\n- No extra charge for re-publish (beyond the monthly tier fee).\n\n- Ideal for rolling out bug fixes, UI tweaks, new pages or backend logic.\n\n<Tip title=\"Safe for iterative improvements\">\nRe-publish as often as you like. It's the quickest, safest way to keep your live app up to date without risking data loss.\n</Tip>\n\n---\n\n## Replace: a blue-green job swap\n\n**Replace** performs a zero-downtime blue-green swap of a different job onto your live app. When you replace a published app, Emergent carries over your user secrets and prompts you to choose what happens to the production database:\n\n- **Keep existing data** - the new job connects to the existing production database.\n- **Start fresh** - the new job gets a new, empty database.\n\n<Warning title=\"Replace is for swapping a different job\">\nReplace is not the same as re-publishing an update to your current app. Use Re-publish to push code changes from your current preview into the live app.\n</Warning>\n\nFor a detailed explanation of each database option and safe migration strategies, see the [Database (MongoDB)](/database-mongodb) page.\n\n---\n\n## Rolling back to an earlier version\n\nIf a change made it live that you need to undo, you can roll back:\n\n- **From Manage Publishing** - each previous published version has a **↺ rollback** icon. Click it to restore that version to your live app.\n- **From the chat timeline** - open history from the top editor toolbar, pick the message to revert to, review the diff of what changed, then click **Rollback**. This restores the code from that point.\n\n<Warning title=\"Rollback affects preview; re-publish to go live\">\nConversation rollback restores the **preview** only - your production URL keeps serving the last published version until you **Re-publish**. Rollback is also destructive: it erases the chat history and code after the selected message, with no roll-forward.\n</Warning>\n\nFor alternatives to in-place rollback, see [Checkpoints: undo anything](/checkpoints-undo-anything) and [Forking](/forking).\n\n---\n\n## Updating a live app safely\n\nOnce real users are on your published app, updates require extra care:\n\n1. **Test thoroughly in preview first** - use the preview environment to verify all changes work as expected.\n2. **Choose Re-publish for code-only changes** - keeps user data intact and minimizes risk.\n3. **Avoid \"Start fresh\" when replacing onto a live app** - this wipes all production data and is almost never appropriate after launch.\n\n<Info title=\"Handling data migrations\">\nIf you need to transform or backfill data, test the migration logic in preview first, then re-publish or replace as appropriate( for MongoDB only). For complex transformations, consider a maintenance window or phased rollout.\n</Info>\n\nFor more on database options during replacement, managing user data safely, and troubleshooting schema conflicts, visit [Database (MongoDB)](/database-mongodb).","order":29,"parent_id":null,"icon":"eye","description":"Preview vs Deployed (separate)","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T06:18:22.157248+00:00","published_at":"2026-09-24T06:18:22.157248+00:00","published_content":"## They are different environments\n\nWhen you build an app in Emergent, you work with **two distinct environments**:\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n- **Preview** - the live sandbox inside the workspace where you test changes as you refine your app with AI agents.\n- **Published** - the production environment serving your real users at your published URL.\n\nEach environment runs with its own URL and server instance. On your **first publish**, Emergent copies your preview's data once into the new production database to seed it; after that the two databases are independent. Later changes you make in preview do not automatically affect the published app until you explicitly push code, and preview edits made after that first publish do **not** sync back into production data.\n\n<Info title=\"Preview is your sandbox\">\nPreview lets you iterate freely, test new features, and fix bugs without risk to your live users. It's the safe place to experiment before committing changes to production.\n</Info>\n\n---\n\n## Why preview changes don't appear live\n\nA common surprise: you've refined your app in preview, the agents have updated the code and tested it successfully - but **none of those changes appear in the published app**.\n\nThis is by design. Emergent keeps the two environments separate so you never accidentally break a live app while iterating. Your published app continues to serve the last version you explicitly pushed, and it will not reflect any preview work until you take action.\n\n<Warning title=\"Changes stay in preview until re-published\">\nEdits, bug fixes, new features and code improvements remain in the preview environment only. To make them live, you must **Re-publish** or **Replace** the published app.\n</Warning>\n\n---\n\n## Re-publish vs Replace\n\nWhen you're ready to push changes from preview to production, Emergent offers two options:\n\n| Action | What it updates | Database impact |\n|--------|----------------|-----------------|\n| **Re-publish** | Code, assets, dependencies | None - keeps existing DB and data |\n| **Replace** | Swaps a different job onto the live app (blue-green) | Keep existing DB or start with a fresh DB |\n\n- Use **Re-publish** when you've only changed UI, logic, styling or dependencies and want to preserve all user data as-is.\n- Use **Replace** when you want to perform a blue-green swap of a different job onto your live app.\n\n---\n\n## Re-publish: push latest code\n\n**Re-publish** copies your preview's code, configuration and assets into a new version alongside the live one and switches traffic at the very end( if it fails, the live app is not affected)- without touching the database.\n\n- The published app's existing MongoDB database remains untouched; all user accounts, records and uploads persist.\n- This is true for every publish **after the first**. Your very first publish seeds the production database once by copying your preview data; from then on the two databases diverge and re-publish never overwrites production data.\n- No extra charge for re-publish (beyond the monthly tier fee).\n\n- Ideal for rolling out bug fixes, UI tweaks, new pages or backend logic.\n\n<Tip title=\"Safe for iterative improvements\">\nRe-publish as often as you like. It's the quickest, safest way to keep your live app up to date without risking data loss.\n</Tip>\n\n---\n\n## Replace: a blue-green job swap\n\n**Replace** performs a zero-downtime blue-green swap of a different job onto your live app. When you replace a published app, Emergent carries over your user secrets and prompts you to choose what happens to the production database:\n\n- **Keep existing data** - the new job connects to the existing production database.\n- **Start fresh** - the new job gets a new, empty database.\n\n<Warning title=\"Replace is for swapping a different job\">\nReplace is not the same as re-publishing an update to your current app. Use Re-publish to push code changes from your current preview into the live app.\n</Warning>\n\nFor a detailed explanation of each database option and safe migration strategies, see the [Database (MongoDB)](/database-mongodb) page.\n\n---\n\n## Rolling back to an earlier version\n\nIf a change made it live that you need to undo, you can roll back:\n\n- **From Manage Publishing** - each previous published version has a **↺ rollback** icon. Click it to restore that version to your live app.\n- **From the chat timeline** - open history from the top editor toolbar, pick the message to revert to, review the diff of what changed, then click **Rollback**. This restores the code from that point.\n\n<Warning title=\"Rollback affects preview; re-publish to go live\">\nConversation rollback restores the **preview** only - your production URL keeps serving the last published version until you **Re-publish**. Rollback is also destructive: it erases the chat history and code after the selected message, with no roll-forward.\n</Warning>\n\nFor alternatives to in-place rollback, see [Checkpoints: undo anything](/checkpoints-undo-anything) and [Forking](/forking).\n\n---\n\n## Updating a live app safely\n\nOnce real users are on your published app, updates require extra care:\n\n1. **Test thoroughly in preview first** - use the preview environment to verify all changes work as expected.\n2. **Choose Re-publish for code-only changes** - keeps user data intact and minimizes risk.\n3. **Avoid \"Start fresh\" when replacing onto a live app** - this wipes all production data and is almost never appropriate after launch.\n\n<Info title=\"Handling data migrations\">\nIf you need to transform or backfill data, test the migration logic in preview first, then re-publish or replace as appropriate( for MongoDB only). For complex transformations, consider a maintenance window or phased rollout.\n</Info>\n\nFor more on database options during replacement, managing user data safely, and troubleshooting schema conflicts, visit [Database (MongoDB)](/database-mongodb).","published_title":"Preview vs Published","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"f04ba93f-1098-407c-9adc-232acb17d03d","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Custom domain","slug":"custom-domain","content":"## Overview\n\nEvery web app published on Emergent receives a free subdomain at `your-app-name.emergent.host`. To present your app under your own brand, add a custom domain through the **Domain** panel(**Preview → Manage → Domain**). Custom domains require you to configure DNS records with your domain registrar (e.g., Cloudflare, Namecheap, GoDaddy) and point them to Emergent's infrastructure. The below steps are for the manual setup. You can also use the **Auto-link** button available at the **Domain** panel to set it up automatically (recommended).\n\nThis page walks you through DNS setup, troubleshooting, and common questions about the default subdomain.\n\n<Note>\nCustom domains are available for **web apps only**. Mobile apps use their own distribution channels (App Store, Play Store) and do not rely on DNS.\n</Note>\n\n---\n\n## DNS: A records + Emergent IPs\n\nTo serve your app at your root domain (e.g., `example.com`), add **two A records** that point to Emergent's shared IP addresses, plus a `www` CNAME. The recommended method is **Auto-Link (Entri)**, which configures these records for you automatically. For manual setup, follow the steps below.\n\n<Steps>\n<Step title=\"Open the Domain panel\">\nIn the Emergent workspace, navigate to **Preview → Manage → Domain** (web apps only). Type your domain name (like `example.com`) in the provided textbox.\n</Step>\n\n<Step title=\"Note the Emergent shared IP addresses\">\nEmergent uses two shared A record IPs, there are no dedicated IPs per app:\n\n- `162.159.142.117`\n- `172.66.2.113`\n\nYou will use both in the next step.\n</Step>\n\n<Step title=\"Create two A records at your DNS provider\">\nLog in to your domain registrar or DNS host (Cloudflare, Namecheap, etc.). Add **two** new **A records**:\n\n**First A record:**\n- **Host / Name**: `@` (or leave blank, depending on your provider)\n- **Type**: `A`\n- **Value / Points to**: `162.159.142.117`\n- **TTL**: `Auto` or `3600` (1 hour)\n\n**Second A record:**\n- **Host / Name**: `@` (or leave blank, depending on your provider)\n- **Type**: `A`\n- **Value / Points to**: `172.66.2.113`\n- **TTL**: `Auto` or `3600` (1 hour)\n\nSave both records.\n</Step>\n\n<Step title=\"Confirm the domain in Emergent\">\nReturn to the custom domain panel, enter your domain (e.g., `example.com`), and click the check status icon. Emergent will check for the A records and provision an SSL certificate once the records are detected.\n</Step>\n</Steps>\n\n<Callout type=\"info\" title=\"SSL provisioning\">\nSSL certificates are issued automatically via **Cloudflare Custom Hostnames** after DNS verification. This usually takes a few minutes but can take up to 24 hours if DNS propagation is slow.\n</Callout>\n\n---\n\n## CNAME (`www`) entry\n\nMost users expect both `example.com` and `www.example.com` to work. Add a **CNAME record** to route `www` traffic to your root domain.\n\n<Steps>\n<Step title=\"Add the CNAME record\">\nIn your DNS provider's dashboard, create a new **CNAME** record:\n\n- **Host / Name**: `www`\n- **Type**: `CNAME`\n- **Value / Points to**: `example.com` (your root domain, no `http://`)\n- **TTL**: `Auto` or `3600`\n\nSave the record.\n</Step>\n\n<Step title=\"Test both URLs\">\nAfter DNS propagates, visit both `https://example.com` and `https://www.example.com`. Both should load your app. Emergent automatically redirects `www` to the root domain (or vice versa, depending on your configuration).\n</Step>\n</Steps>\n\n<Tip>\nSome DNS providers (like Cloudflare) also support **CNAME flattening** or **ALIAS records** at the root. If you prefer to use a CNAME instead of an A record, consult your provider's documentation.\n</Tip>\n\n---\n\n## Troubleshooting a stuck domain\n\nIf your custom domain does not load after adding DNS records, follow these checks:\n\n<AccordionGroup>\n<Accordion title=\"Verify DNS records are correct\">\nUse a DNS lookup tool (e.g., [dnschecker.org](https://dnschecker.org) or `dig example.com` in your terminal) to confirm:\n\n- Both **A records** for `@` (root) point to `162.159.142.117` and `172.66.2.113`.\n- The **CNAME** for `www` points to your root domain.\n\nIf the records are missing or incorrect, update them at your DNS provider and allow a few minutes for propagation.\n</Accordion>\n\n<Accordion title=\"Wait for DNS propagation\">\nDNS changes can take anywhere from a few minutes to 48 hours to propagate globally, depending on your provider and the previous TTL. If you recently added or changed records, wait 1-2 hours and check again.\n</Accordion>\n\n<Accordion title=\"Check SSL certificate status\">\nIn the Emergent **Published versions panel, the custom domain row shows a status badge (e.g., Pending**, **Active**, **Error**). If it says **Pending**, SSL provisioning is in progress. If it says **Error**, click **Details** to see the specific issue (often a DNS mismatch or CAA record blocking certificate issuance).\n</Accordion>\n\n<Accordion title=\"Clear your browser cache\">\nBrowsers and operating systems cache DNS lookups. Try visiting your domain in an **incognito/private window** or run `ipconfig /flushdns` (Windows) / `sudo dscacheutil -flushcache` (macOS) to clear local caches.\n</Accordion>\n</AccordionGroup>\n\n<Warning>\nIf your domain's DNS is managed through **Cloudflare**, your A records and CNAME must be set to **DNS-only (gray cloud) permanently**. Enabling the Cloudflare proxy (orange cloud) at any time will cause Error 1014 and break your custom domain.\n</Warning>\n\n---\n\n## What the Emergent subdomain is\n\nEvery web app on Emergent is assigned a default URL in the format:\n\n```\nhttps://your-app-name.emergent.host\n```\n\nThis subdomain:\n\n- Is **always available**, even if you add a custom domain.\n- Receives the same published versions and updates as your custom domain.\n- Uses a **wildcard SSL certificate** managed by Emergent (always HTTPS).\n- Reflects the **app name** you chose during creation.\n\n<Callout type=\"info\" title=\"Will the subdomain work as-is?\">\nYes. You can share the `your-app-name.emergent.host` URL immediately - no DNS setup required. It is a fully functional production URL. Custom domains are optional and purely for branding.\n</Callout>\n\nIf you are prototyping or running an internal tool, the Emergent subdomain is often sufficient. For customer-facing apps, a custom domain (e.g., `app.yourcompany.com`) is recommended.\n\n---\n\n## Changing the app name & Google auth label\n\n<AccordionGroup>\n<Accordion title=\"Can I rename my app (and subdomain)?\">\nDefault subdomains **cannot be changed**, once assigned, your `your-app-name.emergent.host` URL is permanent and deleted URLs are never reused. If you need a different subdomain, you would need to create a new app.\n\n<Warning>\nIf you use [Google auth](/google-auth) or [Emergent Auth](/emergent-auth-built-in), ensure your authorized redirect URIs in the Google Cloud Console or GitHub OAuth app settings match the subdomain your app is currently using.\n</Warning>\n</Accordion>\n\n<Accordion title=\"Why does Google auth show 'Sign in to [old app name]'?\">\nGoogle's OAuth consent screen displays the **OAuth application name** configured in the Google Cloud Console, not the Emergent app name. To change the label users see:\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com).\n2. Select your project → **APIs & Services** → **OAuth consent screen**.\n3. Update the **Application name** field.\n4. Save changes.\n\nThe new name will appear on the Google sign-in prompt within a few minutes. For more details, see the [Google auth](/google-auth) page.\n</Accordion>\n</AccordionGroup>\n","order":30,"parent_id":null,"icon":"globe","description":"Custom domain","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T06:18:22.910026+00:00","published_at":"2026-09-24T06:18:22.910026+00:00","published_content":"## Overview\n\nEvery web app published on Emergent receives a free subdomain at `your-app-name.emergent.host`. To present your app under your own brand, add a custom domain through the **Domain** panel(**Preview → Manage → Domain**). Custom domains require you to configure DNS records with your domain registrar (e.g., Cloudflare, Namecheap, GoDaddy) and point them to Emergent's infrastructure. The below steps are for the manual setup. You can also use the **Auto-link** button available at the **Domain** panel to set it up automatically (recommended).\n\nThis page walks you through DNS setup, troubleshooting, and common questions about the default subdomain.\n\n<Note>\nCustom domains are available for **web apps only**. Mobile apps use their own distribution channels (App Store, Play Store) and do not rely on DNS.\n</Note>\n\n---\n\n## DNS: A records + Emergent IPs\n\nTo serve your app at your root domain (e.g., `example.com`), add **two A records** that point to Emergent's shared IP addresses, plus a `www` CNAME. The recommended method is **Auto-Link (Entri)**, which configures these records for you automatically. For manual setup, follow the steps below.\n\n<Steps>\n<Step title=\"Open the Domain panel\">\nIn the Emergent workspace, navigate to **Preview → Manage → Domain** (web apps only). Type your domain name (like `example.com`) in the provided textbox.\n</Step>\n\n<Step title=\"Note the Emergent shared IP addresses\">\nEmergent uses two shared A record IPs, there are no dedicated IPs per app:\n\n- `162.159.142.117`\n- `172.66.2.113`\n\nYou will use both in the next step.\n</Step>\n\n<Step title=\"Create two A records at your DNS provider\">\nLog in to your domain registrar or DNS host (Cloudflare, Namecheap, etc.). Add **two** new **A records**:\n\n**First A record:**\n- **Host / Name**: `@` (or leave blank, depending on your provider)\n- **Type**: `A`\n- **Value / Points to**: `162.159.142.117`\n- **TTL**: `Auto` or `3600` (1 hour)\n\n**Second A record:**\n- **Host / Name**: `@` (or leave blank, depending on your provider)\n- **Type**: `A`\n- **Value / Points to**: `172.66.2.113`\n- **TTL**: `Auto` or `3600` (1 hour)\n\nSave both records.\n</Step>\n\n<Step title=\"Confirm the domain in Emergent\">\nReturn to the custom domain panel, enter your domain (e.g., `example.com`), and click the check status icon. Emergent will check for the A records and provision an SSL certificate once the records are detected.\n</Step>\n</Steps>\n\n<Callout type=\"info\" title=\"SSL provisioning\">\nSSL certificates are issued automatically via **Cloudflare Custom Hostnames** after DNS verification. This usually takes a few minutes but can take up to 24 hours if DNS propagation is slow.\n</Callout>\n\n---\n\n## CNAME (`www`) entry\n\nMost users expect both `example.com` and `www.example.com` to work. Add a **CNAME record** to route `www` traffic to your root domain.\n\n<Steps>\n<Step title=\"Add the CNAME record\">\nIn your DNS provider's dashboard, create a new **CNAME** record:\n\n- **Host / Name**: `www`\n- **Type**: `CNAME`\n- **Value / Points to**: `example.com` (your root domain, no `http://`)\n- **TTL**: `Auto` or `3600`\n\nSave the record.\n</Step>\n\n<Step title=\"Test both URLs\">\nAfter DNS propagates, visit both `https://example.com` and `https://www.example.com`. Both should load your app. Emergent automatically redirects `www` to the root domain (or vice versa, depending on your configuration).\n</Step>\n</Steps>\n\n<Tip>\nSome DNS providers (like Cloudflare) also support **CNAME flattening** or **ALIAS records** at the root. If you prefer to use a CNAME instead of an A record, consult your provider's documentation.\n</Tip>\n\n---\n\n## Troubleshooting a stuck domain\n\nIf your custom domain does not load after adding DNS records, follow these checks:\n\n<AccordionGroup>\n<Accordion title=\"Verify DNS records are correct\">\nUse a DNS lookup tool (e.g., [dnschecker.org](https://dnschecker.org) or `dig example.com` in your terminal) to confirm:\n\n- Both **A records** for `@` (root) point to `162.159.142.117` and `172.66.2.113`.\n- The **CNAME** for `www` points to your root domain.\n\nIf the records are missing or incorrect, update them at your DNS provider and allow a few minutes for propagation.\n</Accordion>\n\n<Accordion title=\"Wait for DNS propagation\">\nDNS changes can take anywhere from a few minutes to 48 hours to propagate globally, depending on your provider and the previous TTL. If you recently added or changed records, wait 1-2 hours and check again.\n</Accordion>\n\n<Accordion title=\"Check SSL certificate status\">\nIn the Emergent **Published versions panel, the custom domain row shows a status badge (e.g., Pending**, **Active**, **Error**). If it says **Pending**, SSL provisioning is in progress. If it says **Error**, click **Details** to see the specific issue (often a DNS mismatch or CAA record blocking certificate issuance).\n</Accordion>\n\n<Accordion title=\"Clear your browser cache\">\nBrowsers and operating systems cache DNS lookups. Try visiting your domain in an **incognito/private window** or run `ipconfig /flushdns` (Windows) / `sudo dscacheutil -flushcache` (macOS) to clear local caches.\n</Accordion>\n</AccordionGroup>\n\n<Warning>\nIf your domain's DNS is managed through **Cloudflare**, your A records and CNAME must be set to **DNS-only (gray cloud) permanently**. Enabling the Cloudflare proxy (orange cloud) at any time will cause Error 1014 and break your custom domain.\n</Warning>\n\n---\n\n## What the Emergent subdomain is\n\nEvery web app on Emergent is assigned a default URL in the format:\n\n```\nhttps://your-app-name.emergent.host\n```\n\nThis subdomain:\n\n- Is **always available**, even if you add a custom domain.\n- Receives the same published versions and updates as your custom domain.\n- Uses a **wildcard SSL certificate** managed by Emergent (always HTTPS).\n- Reflects the **app name** you chose during creation.\n\n<Callout type=\"info\" title=\"Will the subdomain work as-is?\">\nYes. You can share the `your-app-name.emergent.host` URL immediately - no DNS setup required. It is a fully functional production URL. Custom domains are optional and purely for branding.\n</Callout>\n\nIf you are prototyping or running an internal tool, the Emergent subdomain is often sufficient. For customer-facing apps, a custom domain (e.g., `app.yourcompany.com`) is recommended.\n\n---\n\n## Changing the app name & Google auth label\n\n<AccordionGroup>\n<Accordion title=\"Can I rename my app (and subdomain)?\">\nDefault subdomains **cannot be changed**, once assigned, your `your-app-name.emergent.host` URL is permanent and deleted URLs are never reused. If you need a different subdomain, you would need to create a new app.\n\n<Warning>\nIf you use [Google auth](/google-auth) or [Emergent Auth](/emergent-auth-built-in), ensure your authorized redirect URIs in the Google Cloud Console or GitHub OAuth app settings match the subdomain your app is currently using.\n</Warning>\n</Accordion>\n\n<Accordion title=\"Why does Google auth show 'Sign in to [old app name]'?\">\nGoogle's OAuth consent screen displays the **OAuth application name** configured in the Google Cloud Console, not the Emergent app name. To change the label users see:\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com).\n2. Select your project → **APIs & Services** → **OAuth consent screen**.\n3. Update the **Application name** field.\n4. Save changes.\n\nThe new name will appear on the Google sign-in prompt within a few minutes. For more details, see the [Google auth](/google-auth) page.\n</Accordion>\n</AccordionGroup>\n","published_title":"Custom domain","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"c2f2665a-abe8-4919-9878-9f7cf4dead06","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Web to Mobile conversion","slug":"web-mobile-conversion-canonical","content":"## What is platform conversion?\n\nEmergent lets you **convert a web app to mobile** through a preview-panel toggle. When you convert, the platform forks your project into a new job and rebuilds the mobile side using Expo/React Native, translating UI frameworks, layout patterns, navigation, and platform-specific idioms, while sharing the same backend between both platforms.\n\n<Info>\nWeb → mobile conversion forks your project into a new job where both the web and mobile apps share the same backend, managed in one project. **Mobile → web conversion is not supported**, if you need a web version of a mobile-only project, you will need to rebuild.\n</Info>\n\n<Warning>\nWeb → mobile conversion is a feature-flagged capability still rolling out. It does **not** support Next.js projects.\n</Warning>\n\n## When to add a mobile app\n\n- **Validated web MVP**: you've validated a web MVP and want native distribution through app stores, without rebuilding or duplicating your backend.\n- **Expanding platform reach**: you need a native mobile presence alongside your existing web app, managed in one project.\n\n---\n\n## How conversion works\n\n<Steps>\n<Step title=\"Find the conversion toggle in the preview panel\">\nOpen your web app's preview panel. If web → mobile conversion is available for your project, you will see an option to **Add Mobile App** (or a platform toggle). This is not in a Publish dropdown, look in the preview panel directly.\n</Step>\n\n<Step title=\"The platform forks a new job\">\nEmergent creates a new forked job. Both the web and mobile sides share the same backend going forward. The mobile side is built as an **Expo/React Native** app.\n</Step>\n\n<Step title=\"Agent rebuilds the UI for mobile\">\nA conversion job runs, rewriting components, restructuring navigation, swapping frameworks (React web → React Native), and adjusting layout for the mobile form factor.\n</Step>\n\n<Step title=\"Review and test the converted app\">\nThe converted app opens in preview mode. Use the embedded preview, Expo Go QR code, or cloud device streaming to test on device. Test thoroughly before publishing live.\n</Step>\n\n<Step title=\"Publish when satisfied\">\nWhen everything works, use the **Publish** button to publish. If issues arise, iterate in chat or continue refining in the preview.\n</Step>\n</Steps>\n\n<Tip title=\"Conversion is a Job\">\nLike any build task, conversion runs as a job and consumes credits. You can watch progress, pause, or cancel if needed.\n</Tip>\n\n---\n\n## What happens to my data and settings during conversion?\n\nBecause web → mobile conversion **forks into a new job**, you should not assume automatic carry-over of data, environment variables, sessions, or uploaded files. Review each of the following carefully after conversion:\n\n- **Database schema and data**: Verify that data is accessible in the new forked job, carry-over is not guaranteed.\n\n- **Environment variables and secrets**: Check that any env vars or secrets you rely on are present in the new job, they are not automatically transferred.\n\n- **Authentication and user sessions**: Login flows and user sessions should be re-tested end-to-end after conversion.\n\n- **Uploaded files and assets**: Uploaded assets should be verified as accessible from the new job context. Note that deletion of uploaded assets is not currently supported (uploads are permanent).\n\n<Note>\nThe agent rebuilds the **UI and navigation** for mobile while the backend is shared. Business logic and API routes continue working through the shared backend, but always verify after a fork.\n</Note>\n\n---\n\n## What’s shared vs. what’s separate\n\n| Component | Behavior |\n|-----------|----------|\n| Database & collections | **Shared**, both platforms use the same MongoDB instance; schema and data are common |\n| Backend / API | **Shared**, both platforms share the same backend; it is not regenerated or duplicated |\n| User accounts & auth | **Shared**, login works across both platforms |\n| Environment variables | **Shared**, API keys and secrets are common to both |\n| UI components | **Separate**, the mobile UI is built in Expo/React Native; the web UI remains as-is |\n| Published app | **Independent**, each platform is published separately, but managed within one project |\n| Third-party integrations | **Reviewed**, some integrations differ by platform (e.g., Stripe and Paystack are hidden on Expo projects; Razorpay and PayPal remain) |\n\n---\n\n## What adapts during web → mobile conversion\n\n### Rebuilt automatically\n\n- **UI components**: buttons, forms, modals, and lists rebuild using React Native patterns (e.g. web `<button>` → `<Pressable>`).\n- **Navigation**: URL-based web routing converts to mobile navigation stacks and tabs.\n- **Responsive layout**: desktop/web layouts condense to mobile-friendly single-column or tabbed views.\n- **Form inputs**: HTML5 inputs map to appropriate mobile keyboard types and pickers.\n\n### What may require adjustment\n\n<Warning title=\"Platform-specific features need review\">\nCapabilities unique to the web platform, browser APIs, OS-level integrations, may not translate directly to mobile. Test these carefully after conversion.\n</Warning>\n\n| Feature | Web → Mobile notes |\n|---------|--------------------|\n| **Camera/microphone** | Native mobile APIs available; permission prompts may need adding |\n| **Push notifications** | Needs mobile push service (FCM/APNs) configured |\n| **Geolocation** | Native mobile APIs are faster/more reliable |\n| **File system access** | Mobile uses app-sandboxed storage |\n| **Print/PDF export** | Not a standard mobile pattern; may need redesign |\n| **Right-click menus** | Replaced with touch-and-hold patterns |\n| **Hover states** | Touch doesn't have hover; replaced with press/active states |\n\n<Info>\nIf your app relies heavily on a specific feature, mention it explicitly in chat during conversion: *\"Keep the QR scanner working on mobile\"* or *\"Preserve the file export button.\"*\n</Info>\n\n---\n\n## Common conversion scenarios\n\n<AccordionGroup>\n<Accordion title=\"I built a dashboard on web. Can I convert it to mobile?\">\nIf web → mobile conversion is available for your project (and it is not a Next.js project), yes. Multi-column layouts will condense to scrollable single-column or tabbed views. Charts and tables adapt to smaller screens, the agent may introduce horizontal scroll for wide tables or summary cards for dense data.\n</Accordion>\n\n<Accordion title=\"I have a mobile app. Can I convert it to web?\">\nMobile → web conversion is not supported. If you need a web version of a mobile-only project, you will need to start a new web project and rebuild.\n</Accordion>\n\n<Accordion title=\"What happens to my environment variables and secrets?\">\nBecause conversion forks into a new job, you should check your environment variables after conversion and re-enter any that are missing. Do not paste secrets into chat, use the Secrets panel (**Preview → Manage → Secrets**) or ask the agent to add them to `.env`, then re-publish.\n</Accordion>\n\n<Accordion title=\"Can I go back if the conversion doesn't work out?\">\nYour original web project is unaffected, conversion creates a new forked job. You can continue working on the original. There is no automated rollback of the conversion itself.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Best practices for smooth conversion\n\n- **Test on real devices**: Use Expo Go or cloud device streaming to test on real iOS/Android devices, simulators catch some but not all platform quirks.\n- **Check authentication flows**: Login, signup, and OAuth redirects must work on mobile.\n- **Review navigation**: Make sure every screen is reachable and back/close buttons behave correctly.\n- **Verify data access**: Confirm your app can read and write data as expected after the fork.\n- **Test edge cases**: Empty states, long text, and landscape orientation on mobile.\n\n<Tip>\nAfter conversion, open the app in preview and click through every major user flow. If something feels off, describe the issue in chat, the agent can fine-tune layout, navigation, or component behavior.\n</Tip>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Mobile apps (Expo)\" icon=\"mobile\" href=\"/mobile-apps-expo\">\nHow mobile apps work on Emergent: Expo Go preview, native builds, signing, and store submission.\n</Card>\n<Card title=\"How apps work here\" icon=\"brain\" href=\"/how-apps-work-here-mental-model\">\nUnderstand Emergent's build system and how the agent structures your app.\n</Card>\n<Card title=\"What is a Job?\" icon=\"list-checks\" href=\"/what-is-a-job\">\nLearn how build tasks (including conversion) run and how to monitor progress.\n</Card>\n<Card title=\"Publish & preview\" icon=\"rocket\" href=\"/publish-and-preview\">\nPublishing your app live after conversion.\n</Card>\n</CardGroup>","order":31,"parent_id":null,"icon":"layers","description":"1. What conversion does: how converting between web and mobile works. CANONICAL page.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T06:18:22.162573+00:00","published_at":"2026-09-24T06:18:22.162573+00:00","published_content":"## What is platform conversion?\n\nEmergent lets you **convert a web app to mobile** through a preview-panel toggle. When you convert, the platform forks your project into a new job and rebuilds the mobile side using Expo/React Native, translating UI frameworks, layout patterns, navigation, and platform-specific idioms, while sharing the same backend between both platforms.\n\n<Info>\nWeb → mobile conversion forks your project into a new job where both the web and mobile apps share the same backend, managed in one project. **Mobile → web conversion is not supported**, if you need a web version of a mobile-only project, you will need to rebuild.\n</Info>\n\n<Warning>\nWeb → mobile conversion is a feature-flagged capability still rolling out. It does **not** support Next.js projects.\n</Warning>\n\n## When to add a mobile app\n\n- **Validated web MVP**: you've validated a web MVP and want native distribution through app stores, without rebuilding or duplicating your backend.\n- **Expanding platform reach**: you need a native mobile presence alongside your existing web app, managed in one project.\n\n---\n\n## How conversion works\n\n<Steps>\n<Step title=\"Find the conversion toggle in the preview panel\">\nOpen your web app's preview panel. If web → mobile conversion is available for your project, you will see an option to **Add Mobile App** (or a platform toggle). This is not in a Publish dropdown, look in the preview panel directly.\n</Step>\n\n<Step title=\"The platform forks a new job\">\nEmergent creates a new forked job. Both the web and mobile sides share the same backend going forward. The mobile side is built as an **Expo/React Native** app.\n</Step>\n\n<Step title=\"Agent rebuilds the UI for mobile\">\nA conversion job runs, rewriting components, restructuring navigation, swapping frameworks (React web → React Native), and adjusting layout for the mobile form factor.\n</Step>\n\n<Step title=\"Review and test the converted app\">\nThe converted app opens in preview mode. Use the embedded preview, Expo Go QR code, or cloud device streaming to test on device. Test thoroughly before publishing live.\n</Step>\n\n<Step title=\"Publish when satisfied\">\nWhen everything works, use the **Publish** button to publish. If issues arise, iterate in chat or continue refining in the preview.\n</Step>\n</Steps>\n\n<Tip title=\"Conversion is a Job\">\nLike any build task, conversion runs as a job and consumes credits. You can watch progress, pause, or cancel if needed.\n</Tip>\n\n---\n\n## What happens to my data and settings during conversion?\n\nBecause web → mobile conversion **forks into a new job**, you should not assume automatic carry-over of data, environment variables, sessions, or uploaded files. Review each of the following carefully after conversion:\n\n- **Database schema and data**: Verify that data is accessible in the new forked job, carry-over is not guaranteed.\n\n- **Environment variables and secrets**: Check that any env vars or secrets you rely on are present in the new job, they are not automatically transferred.\n\n- **Authentication and user sessions**: Login flows and user sessions should be re-tested end-to-end after conversion.\n\n- **Uploaded files and assets**: Uploaded assets should be verified as accessible from the new job context. Note that deletion of uploaded assets is not currently supported (uploads are permanent).\n\n<Note>\nThe agent rebuilds the **UI and navigation** for mobile while the backend is shared. Business logic and API routes continue working through the shared backend, but always verify after a fork.\n</Note>\n\n---\n\n## What’s shared vs. what’s separate\n\n| Component | Behavior |\n|-----------|----------|\n| Database & collections | **Shared**, both platforms use the same MongoDB instance; schema and data are common |\n| Backend / API | **Shared**, both platforms share the same backend; it is not regenerated or duplicated |\n| User accounts & auth | **Shared**, login works across both platforms |\n| Environment variables | **Shared**, API keys and secrets are common to both |\n| UI components | **Separate**, the mobile UI is built in Expo/React Native; the web UI remains as-is |\n| Published app | **Independent**, each platform is published separately, but managed within one project |\n| Third-party integrations | **Reviewed**, some integrations differ by platform (e.g., Stripe and Paystack are hidden on Expo projects; Razorpay and PayPal remain) |\n\n---\n\n## What adapts during web → mobile conversion\n\n### Rebuilt automatically\n\n- **UI components**: buttons, forms, modals, and lists rebuild using React Native patterns (e.g. web `<button>` → `<Pressable>`).\n- **Navigation**: URL-based web routing converts to mobile navigation stacks and tabs.\n- **Responsive layout**: desktop/web layouts condense to mobile-friendly single-column or tabbed views.\n- **Form inputs**: HTML5 inputs map to appropriate mobile keyboard types and pickers.\n\n### What may require adjustment\n\n<Warning title=\"Platform-specific features need review\">\nCapabilities unique to the web platform, browser APIs, OS-level integrations, may not translate directly to mobile. Test these carefully after conversion.\n</Warning>\n\n| Feature | Web → Mobile notes |\n|---------|--------------------|\n| **Camera/microphone** | Native mobile APIs available; permission prompts may need adding |\n| **Push notifications** | Needs mobile push service (FCM/APNs) configured |\n| **Geolocation** | Native mobile APIs are faster/more reliable |\n| **File system access** | Mobile uses app-sandboxed storage |\n| **Print/PDF export** | Not a standard mobile pattern; may need redesign |\n| **Right-click menus** | Replaced with touch-and-hold patterns |\n| **Hover states** | Touch doesn't have hover; replaced with press/active states |\n\n<Info>\nIf your app relies heavily on a specific feature, mention it explicitly in chat during conversion: *\"Keep the QR scanner working on mobile\"* or *\"Preserve the file export button.\"*\n</Info>\n\n---\n\n## Common conversion scenarios\n\n<AccordionGroup>\n<Accordion title=\"I built a dashboard on web. Can I convert it to mobile?\">\nIf web → mobile conversion is available for your project (and it is not a Next.js project), yes. Multi-column layouts will condense to scrollable single-column or tabbed views. Charts and tables adapt to smaller screens, the agent may introduce horizontal scroll for wide tables or summary cards for dense data.\n</Accordion>\n\n<Accordion title=\"I have a mobile app. Can I convert it to web?\">\nMobile → web conversion is not supported. If you need a web version of a mobile-only project, you will need to start a new web project and rebuild.\n</Accordion>\n\n<Accordion title=\"What happens to my environment variables and secrets?\">\nBecause conversion forks into a new job, you should check your environment variables after conversion and re-enter any that are missing. Do not paste secrets into chat, use the Secrets panel (**Preview → Manage → Secrets**) or ask the agent to add them to `.env`, then re-publish.\n</Accordion>\n\n<Accordion title=\"Can I go back if the conversion doesn't work out?\">\nYour original web project is unaffected, conversion creates a new forked job. You can continue working on the original. There is no automated rollback of the conversion itself.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Best practices for smooth conversion\n\n- **Test on real devices**: Use Expo Go or cloud device streaming to test on real iOS/Android devices, simulators catch some but not all platform quirks.\n- **Check authentication flows**: Login, signup, and OAuth redirects must work on mobile.\n- **Review navigation**: Make sure every screen is reachable and back/close buttons behave correctly.\n- **Verify data access**: Confirm your app can read and write data as expected after the fork.\n- **Test edge cases**: Empty states, long text, and landscape orientation on mobile.\n\n<Tip>\nAfter conversion, open the app in preview and click through every major user flow. If something feels off, describe the issue in chat, the agent can fine-tune layout, navigation, or component behavior.\n</Tip>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Mobile apps (Expo)\" icon=\"mobile\" href=\"/mobile-apps-expo\">\nHow mobile apps work on Emergent: Expo Go preview, native builds, signing, and store submission.\n</Card>\n<Card title=\"How apps work here\" icon=\"brain\" href=\"/how-apps-work-here-mental-model\">\nUnderstand Emergent's build system and how the agent structures your app.\n</Card>\n<Card title=\"What is a Job?\" icon=\"list-checks\" href=\"/what-is-a-job\">\nLearn how build tasks (including conversion) run and how to monitor progress.\n</Card>\n<Card title=\"Publish & preview\" icon=\"rocket\" href=\"/publish-and-preview\">\nPublishing your app live after conversion.\n</Card>\n</CardGroup>","published_title":"Web to Mobile conversion","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"67a3e403-2a3e-41b6-8c68-8d32362a72fc","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Starting the process","slug":"starting-the-process","content":"## What can be built?\n\nEmergent's mobile build system supports two types of mobile applications:\n\n- **Native Android apps** - compiled APKs that install on Android devices and publish to Google Play Console.\n- **Native iOS apps** - built and uploaded directly to your TestFlight for testing and App Store submission (no IPA file is handed to you).\n\n<Note title=\"Platform support note\">\nApple Watch and iPad apps can be coded (Swift/SwiftUI) within Emergent but cannot yet be published to the App Store through the platform. Support for these platforms is coming soon.\n</Note>\n\nAll mobile apps are built using **React Native** and the **Expo framework**, which share a single codebase for both iOS and Android.\n\n---\n\n## Requirements\n\nBefore you start building, make sure you have:\n\n<Steps>\n<Step title=\"An Emergent account\">\nSign up or log in at [app.emergent.sh](https://app.emergent.sh). Native builds (APK/IPA) require a **paid plan**; previewing via Expo Go is free.\n</Step>\n\n<Step title=\"The Expo Go app (for testing)\">\nDownload **Expo Go** on your phone - it's free on both the App Store (iOS) and Google Play (Android). You'll use it to scan a QR code and preview your app live without publishing.\n</Step>\n\n<Step title=\"Developer accounts (for publishing)\">\nTo ship to production, you need:\n\n- **Apple Developer Program** account ($99/year) for iOS.\n- **Google Play Console** account (one-time $25 fee) for Android.\n\n<Warning>\nApple account approval takes **24-48 hours**. Create your account early in the process to avoid delays when you're ready to publish.\n</Warning>\n</Step>\n</Steps>\n\nFor more on the publishing step, see [Publishing to the stores](/publishing-to-the-stores).\n\n---\n\n## What is Expo?\n\n**Expo** is the open-source framework and toolchain that powers every mobile app you build in Emergent. It sits on top of React Native and provides:\n\n- A managed build service (no Xcode or Android Studio required on your machine).\n- A comprehensive library of native modules (camera, location, notifications, etc.).\n\n**Expo Go is a free companion app for iOS and Android. During development, you scan a QR code from the Emergent workspace and your app runs live on your device** - no need to compile an APK, no App Store submission, no waiting. Code changes appear instantly.\n\n<Tip>\nThink of Expo Go as a live sandbox: it's perfect for prototyping, iteration, and demos. When you're ready to ship, Emergent builds a standalone binary you submit to the stores.\n</Tip>\n\n---\n\n## Development workflow\n\nBuilding a mobile app in Emergent follows a tight feedback loop between you and the agent:\n\n<Steps>\n<Step title=\"Open a new Mobile App job and describe your app\">\n\nNavigate to the **Build › Mobile Apps** section of your workspace. Start a new conversation with the Mobile Agent and describe what you want to build - features, screens, data, design preferences, integrations.\n</Step>\n\n<Step title=\"Answer clarifying questions\">\nThe agent will ask follow-up questions about authentication, navigation style, API endpoints, branding, and any ambiguities in your request. Answer these in the chat to refine the spec.\n</Step>\n\n<Step title=\"Preview live on your phone via Expo Go\">\nOnce the agent generates the app, it displays a **QR code in the workspace. Open Expo Go on your phone, tap Scan QR code**, and point your camera at the screen. Your app launches immediately.\n\n<Info>\nThe preview is cloud-hosted via Expo tunnel, the only requirement is that your phone is online. If you see a connection error, check your network connection.\n</Info>\n</Step>\n\n<Step title=\"Iterate and debug with the agent\">\nTest the app on your device. If something is broken or missing, describe the issue in the chat. The agent will update the code, and the preview reloads automatically. Repeat until you're satisfied.\n</Step>\n\n<Step title=\"Move to publishing when ready\">\nWhen the app is stable and feature-complete, press **Publish** to publish the app first. Once published, you'll see **Publish to App Store** and **Publish to Play Store** options - tapping one generates the production build. See [Publishing to the stores](/publishing-to-the-stores) for the full flow. Native builds require a **paid Emergent plan**.\n</Step>\n</Steps>\n\n<Tip title=\"Converting an existing web app?\">\nIf you've already built a web app in Emergent and want a mobile version, see [Web to Mobile conversion](/web-mobile-conversion-canonical) for guidance on adapting layouts, navigation, and state.\n</Tip>\n\nFor a step-by-step walkthrough of your first build, see [Your first build (walkthrough)](/start-with-your-idea). For an overview of how Emergent turns chat into published apps, read [The chat-to-published app flow](/the-chat-to-deployment-flow).","order":32,"parent_id":null,"icon":"rocket","description":"Starting the process","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.138711+00:00","published_at":"2026-09-24T14:08:11.138711+00:00","published_content":"## What can be built?\n\nEmergent's mobile build system supports two types of mobile applications:\n\n- **Native Android apps** - compiled APKs that install on Android devices and publish to Google Play Console.\n- **Native iOS apps** - built and uploaded directly to your TestFlight for testing and App Store submission (no IPA file is handed to you).\n\n<Note title=\"Platform support note\">\nApple Watch and iPad apps can be coded (Swift/SwiftUI) within Emergent but cannot yet be published to the App Store through the platform. Support for these platforms is coming soon.\n</Note>\n\nAll mobile apps are built using **React Native** and the **Expo framework**, which share a single codebase for both iOS and Android.\n\n---\n\n## Requirements\n\nBefore you start building, make sure you have:\n\n<Steps>\n<Step title=\"An Emergent account\">\nSign up or log in at [app.emergent.sh](https://app.emergent.sh). Native builds (APK/IPA) require a **paid plan**; previewing via Expo Go is free.\n</Step>\n\n<Step title=\"The Expo Go app (for testing)\">\nDownload **Expo Go** on your phone - it's free on both the App Store (iOS) and Google Play (Android). You'll use it to scan a QR code and preview your app live without publishing.\n</Step>\n\n<Step title=\"Developer accounts (for publishing)\">\nTo ship to production, you need:\n\n- **Apple Developer Program** account ($99/year) for iOS.\n- **Google Play Console** account (one-time $25 fee) for Android.\n\n<Warning>\nApple account approval takes **24-48 hours**. Create your account early in the process to avoid delays when you're ready to publish.\n</Warning>\n</Step>\n</Steps>\n\nFor more on the publishing step, see [Publishing to the stores](/publishing-to-the-stores).\n\n---\n\n## What is Expo?\n\n**Expo** is the open-source framework and toolchain that powers every mobile app you build in Emergent. It sits on top of React Native and provides:\n\n- A managed build service (no Xcode or Android Studio required on your machine).\n- A comprehensive library of native modules (camera, location, notifications, etc.).\n\n**Expo Go is a free companion app for iOS and Android. During development, you scan a QR code from the Emergent workspace and your app runs live on your device** - no need to compile an APK, no App Store submission, no waiting. Code changes appear instantly.\n\n<Tip>\nThink of Expo Go as a live sandbox: it's perfect for prototyping, iteration, and demos. When you're ready to ship, Emergent builds a standalone binary you submit to the stores.\n</Tip>\n\n---\n\n## Development workflow\n\nBuilding a mobile app in Emergent follows a tight feedback loop between you and the agent:\n\n<Steps>\n<Step title=\"Open a new Mobile App job and describe your app\">\n\nNavigate to the **Build › Mobile Apps** section of your workspace. Start a new conversation with the Mobile Agent and describe what you want to build - features, screens, data, design preferences, integrations.\n</Step>\n\n<Step title=\"Answer clarifying questions\">\nThe agent will ask follow-up questions about authentication, navigation style, API endpoints, branding, and any ambiguities in your request. Answer these in the chat to refine the spec.\n</Step>\n\n<Step title=\"Preview live on your phone via Expo Go\">\nOnce the agent generates the app, it displays a **QR code in the workspace. Open Expo Go on your phone, tap Scan QR code**, and point your camera at the screen. Your app launches immediately.\n\n<Info>\nThe preview is cloud-hosted via Expo tunnel, the only requirement is that your phone is online. If you see a connection error, check your network connection.\n</Info>\n</Step>\n\n<Step title=\"Iterate and debug with the agent\">\nTest the app on your device. If something is broken or missing, describe the issue in the chat. The agent will update the code, and the preview reloads automatically. Repeat until you're satisfied.\n</Step>\n\n<Step title=\"Move to publishing when ready\">\nWhen the app is stable and feature-complete, press **Publish** to publish the app first. Once published, you'll see **Publish to App Store** and **Publish to Play Store** options - tapping one generates the production build. See [Publishing to the stores](/publishing-to-the-stores) for the full flow. Native builds require a **paid Emergent plan**.\n</Step>\n</Steps>\n\n<Tip title=\"Converting an existing web app?\">\nIf you've already built a web app in Emergent and want a mobile version, see [Web to Mobile conversion](/web-mobile-conversion-canonical) for guidance on adapting layouts, navigation, and state.\n</Tip>\n\nFor a step-by-step walkthrough of your first build, see [Your first build (walkthrough)](/start-with-your-idea). For an overview of how Emergent turns chat into published apps, read [The chat-to-published app flow](/the-chat-to-deployment-flow).","published_title":"Starting the process","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"9d7d7278-668f-41c3-bfc2-c32740a9dbec","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Pre-publish health check","slug":"pre-publish-health-check","content":"## Why run a pre-publish health check?\n\nBefore you commit to a production build or submit your mobile app to the App Store or Google Play, it's critical to verify that the app behaves as expected on real devices. A pre-publish health check catches UI glitches, navigation issues, API errors, and performance problems **before** they reach your users - saving you time and embarrassment.\n\nEmergent generates a live preview URL for every mobile app. Use it to test thoroughly before you trigger a production build or start the [publishing to the stores](/publishing-to-the-stores) process.\n\n---\n\n## Preview & test the mobile app first\n\n<Info title=\"Test early, test often\">\nYour workspace provides an instant preview of the mobile app. Open it on your phone to check layout, navigation, and features - all without waiting for a compile.\n</Info>\n\nEvery time the AI agents rebuild your mobile app, Emergent updates the preview. You can:\n\n- Open the preview URL in your browser (desktop or mobile) to see a web-based simulation.\n- Scan the QR code with your phone to launch the live app in Expo Go (see below).\n- Navigate through every screen, tap buttons, fill forms, and verify API calls.\n\n**What to check:**\n\n- UI renders correctly on both iOS and Android (test on at least one device from each platform if possible).\n- Navigation flows work end-to-end (tab bars, drawer menus, deep links).\n- Forms validate input and display error messages.\n- Images, fonts, and icons load.\n- API calls succeed (check network panel or logs if something breaks).\n- Authentication flows and third-party SDKs behave as expected. (Push notifications can't be tested in preview - generate a build and test on a physical device.)\n\nIf you spot a bug, describe it in chat - Emergent's agents will fix the code and regenerate the preview. Repeat until the app is solid.\n\n---\n\n## Local testing & testing on your phone with Expo Go\n\nThe fastest way to test your mobile app on a real device is with **Expo Go**, a free companion app that runs Expo projects instantly - no Xcode, no Android Studio, no builds.\n\n<Steps>\n<Step title=\"Install Expo Go on your phone\">\nDownload **Expo Go** from the [App Store](https://apps.apple.com/app/expo-go/id982107779) (iOS) or [Google Play](https://play.google.com/store/apps/details?id=host.exp.exponent) (Android). It's free and maintained by Expo.\n</Step>\n\n<Step title=\"Open the preview in your workspace\">\nIn the Emergent workspace, locate the mobile app preview panel. You'll see a QR code and a preview URL. See [a tour of the workspace](/a-tour-of-the-workspace) if you need help finding it.\n</Step>\n\n<Step title=\"Scan the QR code\">\n- **iOS**: Open **Expo Go** and scan the QR code from inside the app. Newer projects use device-code auth instead of a QR code.\n- **Android**: Open Expo Go and tap **Scan QR Code**, then point your camera at the code.\n\nThe app will load and run directly on your device, connected to Emergent's live preview server.\n</Step>\n\n<Step title=\"Iterate and re-test\">\nMake changes in chat, wait for the agents to rebuild, and the app in Expo Go will **hot-reload automatically** - usually within seconds. You can iterate quickly without leaving your phone.\n</Step>\n</Steps>\n\n<Tip title=\"Use Expo Go for all pre-publish testing\">\nExpo Go gives you a production-like experience on real hardware. Test gestures, animations, keyboard behavior, and camera/location permissions. Only move to a full production build once the app is stable.\n</Tip>\n\n<Warning title=\"Expo Go limitations\">\nExpo Go cannot run apps with custom native code (e.g., certain third-party SDKs or native modules outside the Expo SDK). If your app uses such features, you'll need a development build or a production build. Most Emergent apps work fine in Expo Go.\n</Warning>\n\n---\n\n## Build plans & requirements\n\nWhen you're ready to generate a production build - either for local testing, TestFlight/internal testing, or store submission - you trigger a native build from the Publish panel. Emergent manages the Expo/EAS account on your behalf; you never need to create an Expo account, install eas-cli, purchase EAS credits, or edit **eas.json**.\n\n<Note title=\"Paid Emergent plan required\">\nNative builds (APK/AAB/IPA) require a **paid Emergent plan** (Standard or above). The gate is your Emergent subscription, not Expo credits. See [plans & the free tier](/plans-the-free-tier) for how Emergent's own pricing works.\n</Note>\n\n### How builds are triggered in Emergent\n\nWhen you trigger a native build from the Publish panel, the platform:\n\n1. Builds from your **last published code** (fix any issues → re-publish via Re-publish → then trigger the build, this is the most common gotcha).\n2. Runs the EAS build process using Emergent's managed Expo account.\n3. Queues the build on Expo's servers.\n4. Returns the build artifacts once complete. Android: an APK and an AAB - the AAB is what you upload to the Google Play Console, and the APK can't be tested on a local device without Expo Go. iOS: no IPA is provided - Emergent uploads the build directly to your TestFlight.\n\nSee [Start with your idea](/start-with-your-idea) for step-by-step instructions.\n","order":33,"parent_id":null,"icon":"shield-check","description":"Pre-publish health check","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.127038+00:00","published_at":"2026-09-24T14:08:11.127038+00:00","published_content":"## Why run a pre-publish health check?\n\nBefore you commit to a production build or submit your mobile app to the App Store or Google Play, it's critical to verify that the app behaves as expected on real devices. A pre-publish health check catches UI glitches, navigation issues, API errors, and performance problems **before** they reach your users - saving you time and embarrassment.\n\nEmergent generates a live preview URL for every mobile app. Use it to test thoroughly before you trigger a production build or start the [publishing to the stores](/publishing-to-the-stores) process.\n\n---\n\n## Preview & test the mobile app first\n\n<Info title=\"Test early, test often\">\nYour workspace provides an instant preview of the mobile app. Open it on your phone to check layout, navigation, and features - all without waiting for a compile.\n</Info>\n\nEvery time the AI agents rebuild your mobile app, Emergent updates the preview. You can:\n\n- Open the preview URL in your browser (desktop or mobile) to see a web-based simulation.\n- Scan the QR code with your phone to launch the live app in Expo Go (see below).\n- Navigate through every screen, tap buttons, fill forms, and verify API calls.\n\n**What to check:**\n\n- UI renders correctly on both iOS and Android (test on at least one device from each platform if possible).\n- Navigation flows work end-to-end (tab bars, drawer menus, deep links).\n- Forms validate input and display error messages.\n- Images, fonts, and icons load.\n- API calls succeed (check network panel or logs if something breaks).\n- Authentication flows and third-party SDKs behave as expected. (Push notifications can't be tested in preview - generate a build and test on a physical device.)\n\nIf you spot a bug, describe it in chat - Emergent's agents will fix the code and regenerate the preview. Repeat until the app is solid.\n\n---\n\n## Local testing & testing on your phone with Expo Go\n\nThe fastest way to test your mobile app on a real device is with **Expo Go**, a free companion app that runs Expo projects instantly - no Xcode, no Android Studio, no builds.\n\n<Steps>\n<Step title=\"Install Expo Go on your phone\">\nDownload **Expo Go** from the [App Store](https://apps.apple.com/app/expo-go/id982107779) (iOS) or [Google Play](https://play.google.com/store/apps/details?id=host.exp.exponent) (Android). It's free and maintained by Expo.\n</Step>\n\n<Step title=\"Open the preview in your workspace\">\nIn the Emergent workspace, locate the mobile app preview panel. You'll see a QR code and a preview URL. See [a tour of the workspace](/a-tour-of-the-workspace) if you need help finding it.\n</Step>\n\n<Step title=\"Scan the QR code\">\n- **iOS**: Open **Expo Go** and scan the QR code from inside the app. Newer projects use device-code auth instead of a QR code.\n- **Android**: Open Expo Go and tap **Scan QR Code**, then point your camera at the code.\n\nThe app will load and run directly on your device, connected to Emergent's live preview server.\n</Step>\n\n<Step title=\"Iterate and re-test\">\nMake changes in chat, wait for the agents to rebuild, and the app in Expo Go will **hot-reload automatically** - usually within seconds. You can iterate quickly without leaving your phone.\n</Step>\n</Steps>\n\n<Tip title=\"Use Expo Go for all pre-publish testing\">\nExpo Go gives you a production-like experience on real hardware. Test gestures, animations, keyboard behavior, and camera/location permissions. Only move to a full production build once the app is stable.\n</Tip>\n\n<Warning title=\"Expo Go limitations\">\nExpo Go cannot run apps with custom native code (e.g., certain third-party SDKs or native modules outside the Expo SDK). If your app uses such features, you'll need a development build or a production build. Most Emergent apps work fine in Expo Go.\n</Warning>\n\n---\n\n## Build plans & requirements\n\nWhen you're ready to generate a production build - either for local testing, TestFlight/internal testing, or store submission - you trigger a native build from the Publish panel. Emergent manages the Expo/EAS account on your behalf; you never need to create an Expo account, install eas-cli, purchase EAS credits, or edit **eas.json**.\n\n<Note title=\"Paid Emergent plan required\">\nNative builds (APK/AAB/IPA) require a **paid Emergent plan** (Standard or above). The gate is your Emergent subscription, not Expo credits. See [plans & the free tier](/plans-the-free-tier) for how Emergent's own pricing works.\n</Note>\n\n### How builds are triggered in Emergent\n\nWhen you trigger a native build from the Publish panel, the platform:\n\n1. Builds from your **last published code** (fix any issues → re-publish via Re-publish → then trigger the build, this is the most common gotcha).\n2. Runs the EAS build process using Emergent's managed Expo account.\n3. Queues the build on Expo's servers.\n4. Returns the build artifacts once complete. Android: an APK and an AAB - the AAB is what you upload to the Google Play Console, and the APK can't be tested on a local device without Expo Go. iOS: no IPA is provided - Emergent uploads the build directly to your TestFlight.\n\nSee [Start with your idea](/start-with-your-idea) for step-by-step instructions.\n","published_title":"Pre-publish health check","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"5ee45e86-ce7c-4266-8dca-e5aba1d02b83","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Database & data on mobile","slug":"database-data-on-mobile","content":"## Shared fundamentals\n\nMobile apps built on Emergent use the same MongoDB backend as web apps. The database URL model, storage limits, and core behavior are identical across platforms.\n\nFor a complete explanation of how database URLs work, connection strings, storage quotas, and data persistence, see the [Database (MongoDB)](/database-mongodb) page.\n\nKey points for mobile:\n\n- Each Emergent app gets its own database on a shared Atlas cluster with a unique connection string (Dedicated Database is a paid upgrade)\n- The database is hosted remotely and accessed over HTTPS - your mobile app talks to the same cloud database as the web version\n- All CRUD operations, indexes, and collections work identically on iOS, Android, and web\n\n<Note>\nMobile apps do **not** bundle a local database. All data lives in the cloud MongoDB instance provisioned for your app. Note that preview and production databases are separate.\n</Note>\n\n## Re-publish as an update\n\nWhen you modify your mobile app's backend, database schema, or business logic and want to push that change to users, you must **re-publish** the app.\n\nUnlike web apps (which update instantly on the next page load), mobile apps are distributed as signed binaries with fixed bundle IDs. Backend changes (such as database migrations or API endpoint tweaks) ship by re-publishing, no store review is required for those. For changes to the app itself, including JS-only changes, you need to re-publish and generate a new build - Emergent does not support over-the-air (OTA) updates.\n\n<Steps>\n<Step title=\"Rebuild the mobile app\">\nTrigger a new build in Emergent. The agent will increment the version number and compile fresh iOS/Android binaries.\n</Step>\n\n<Step title=\"Submit to the stores\">\nUpload the new build to App Store Connect (iOS) and Google Play Console (Android). Both stores will review the update.\n</Step>\n\n<Step title=\"Users receive the update\">\nOnce approved, existing users receive the updated app.\n</Step>\n</Steps>\n\n<Warning title=\"Store review applies to app changes\">\nStore review times (hours to days) and user adoption lag (days to weeks) apply to store submissions. Backend-only updates do not require store resubmission.\n</Warning>\n\n**Database implications:**\nThe database itself does **not** re-publish. The same MongoDB database persists across versions. When you re-publish:\n\n- Existing user data remains intact\n- Schema changes (new collections, fields, indexes) take effect immediately on the backend\n- Old app versions still in the wild will continue querying the *updated* database - ensure backward compatibility or force a minimum version\n\n## Fork to experiment safely\n\nInstead of changing your live app directly, you can **fork** it. Think of a fork like a branch: your main app keeps running untouched while you try out a feature, a redesign or a major refactor on a parallel copy.\n\nA fork gives you:\n\n- **The same codebase**, cloned at the fork point\n- **The same bundle ID / package name**: your app's identity carries over automatically - there is no option to change it during the fork (the agent can change it later if you ask, but see the warning below)\n- **Independent builds**: the fork generates its own build artifacts, separate from the original\n- **A database decision later, not now**: forking doesn't touch your data. If the original app was published, you'll be asked to choose between databases when you publish the fork\n\n**When to fork:**\n\n- You're testing a major feature or refactor and don't want to touch the app your users have\n- You want to experiment on a parallel copy without any risk to the original\n\n**How to fork:**\n\n<Steps>\n<Step title=\"Open the + menu in the chat box\">\n\nIn the chat box, click the **+** button.\n</Step>\n\n<Step title=\"Select Fork this chat\">\n\nChoose **Fork this chat**. Emergent clones your app into a new forked chat; the original keeps running untouched.\n</Step>\n\n<Step title=\"Choose the database when you publish\">\n\nThere is no database option at fork time. When you publish the forked app - if the original app was already published - you'll be asked at that point to choose which database it should use.\n</Step>\n</Steps>\n\n<Warning title=\"Don't fork to launch a second app in the stores\">\nA fork is for experimenting, not for shipping a separate app. Your store listing is tied to your Apple Developer team, and a forked build - even with a changed bundle ID - can conflict with the existing listing. If you want to publish a genuinely separate app to the App Store or Play Store, contact support first to set it up the right way.\n</Warning>\n\n## What carries over\n\nHow your database and user data are affected depends on whether you **update** (re-publish) or **fork**.\n\n| Action | Database | User data | Bundle ID | Store listing |\n|--------|----------|-----------|-----------|---------------|\n| **Re-publish (update)** | Same database, schema changes apply | Persists; all users keep their data | Unchanged | Same app, new version number |\n| **Fork** | Unchanged at fork time; you choose which database the fork uses when you publish it (the option appears if the original app was published) | Depends on the database you choose at publish time | Same ID carries over (agent can change it on request) | Same team and listing - do not submit a fork as a new app |\n\n**Re-publish:**\n- Database connection string stays the same\n- Existing collections and documents remain\n- Schema migrations (new fields, indexes) affect all app versions immediately\n- Users who haven't updated yet will query the *new* schema - plan for backward compatibility\n\n**Fork:**\n- Forking itself doesn't touch any data - the database decision comes later, when you publish the forked app\n- If the original app was published, publishing the fork asks you to choose between databases\n- Your bundle ID / package name carries over automatically\n\n<Tip>\nIf you need to selectively migrate or transform data after a fork, you can export collections and import them as needed. See the [Database (MongoDB)](/database-mongodb) page for connection details.\n</Tip>","order":34,"parent_id":null,"icon":"database","description":"Mobile data flow - see canonical Database (MongoDB) page for shared fundamentals.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.231413+00:00","published_at":"2026-09-24T14:08:11.231413+00:00","published_content":"## Shared fundamentals\n\nMobile apps built on Emergent use the same MongoDB backend as web apps. The database URL model, storage limits, and core behavior are identical across platforms.\n\nFor a complete explanation of how database URLs work, connection strings, storage quotas, and data persistence, see the [Database (MongoDB)](/database-mongodb) page.\n\nKey points for mobile:\n\n- Each Emergent app gets its own database on a shared Atlas cluster with a unique connection string (Dedicated Database is a paid upgrade)\n- The database is hosted remotely and accessed over HTTPS - your mobile app talks to the same cloud database as the web version\n- All CRUD operations, indexes, and collections work identically on iOS, Android, and web\n\n<Note>\nMobile apps do **not** bundle a local database. All data lives in the cloud MongoDB instance provisioned for your app. Note that preview and production databases are separate.\n</Note>\n\n## Re-publish as an update\n\nWhen you modify your mobile app's backend, database schema, or business logic and want to push that change to users, you must **re-publish** the app.\n\nUnlike web apps (which update instantly on the next page load), mobile apps are distributed as signed binaries with fixed bundle IDs. Backend changes (such as database migrations or API endpoint tweaks) ship by re-publishing, no store review is required for those. For changes to the app itself, including JS-only changes, you need to re-publish and generate a new build - Emergent does not support over-the-air (OTA) updates.\n\n<Steps>\n<Step title=\"Rebuild the mobile app\">\nTrigger a new build in Emergent. The agent will increment the version number and compile fresh iOS/Android binaries.\n</Step>\n\n<Step title=\"Submit to the stores\">\nUpload the new build to App Store Connect (iOS) and Google Play Console (Android). Both stores will review the update.\n</Step>\n\n<Step title=\"Users receive the update\">\nOnce approved, existing users receive the updated app.\n</Step>\n</Steps>\n\n<Warning title=\"Store review applies to app changes\">\nStore review times (hours to days) and user adoption lag (days to weeks) apply to store submissions. Backend-only updates do not require store resubmission.\n</Warning>\n\n**Database implications:**\nThe database itself does **not** re-publish. The same MongoDB database persists across versions. When you re-publish:\n\n- Existing user data remains intact\n- Schema changes (new collections, fields, indexes) take effect immediately on the backend\n- Old app versions still in the wild will continue querying the *updated* database - ensure backward compatibility or force a minimum version\n\n## Fork to experiment safely\n\nInstead of changing your live app directly, you can **fork** it. Think of a fork like a branch: your main app keeps running untouched while you try out a feature, a redesign or a major refactor on a parallel copy.\n\nA fork gives you:\n\n- **The same codebase**, cloned at the fork point\n- **The same bundle ID / package name**: your app's identity carries over automatically - there is no option to change it during the fork (the agent can change it later if you ask, but see the warning below)\n- **Independent builds**: the fork generates its own build artifacts, separate from the original\n- **A database decision later, not now**: forking doesn't touch your data. If the original app was published, you'll be asked to choose between databases when you publish the fork\n\n**When to fork:**\n\n- You're testing a major feature or refactor and don't want to touch the app your users have\n- You want to experiment on a parallel copy without any risk to the original\n\n**How to fork:**\n\n<Steps>\n<Step title=\"Open the + menu in the chat box\">\n\nIn the chat box, click the **+** button.\n</Step>\n\n<Step title=\"Select Fork this chat\">\n\nChoose **Fork this chat**. Emergent clones your app into a new forked chat; the original keeps running untouched.\n</Step>\n\n<Step title=\"Choose the database when you publish\">\n\nThere is no database option at fork time. When you publish the forked app - if the original app was already published - you'll be asked at that point to choose which database it should use.\n</Step>\n</Steps>\n\n<Warning title=\"Don't fork to launch a second app in the stores\">\nA fork is for experimenting, not for shipping a separate app. Your store listing is tied to your Apple Developer team, and a forked build - even with a changed bundle ID - can conflict with the existing listing. If you want to publish a genuinely separate app to the App Store or Play Store, contact support first to set it up the right way.\n</Warning>\n\n## What carries over\n\nHow your database and user data are affected depends on whether you **update** (re-publish) or **fork**.\n\n| Action | Database | User data | Bundle ID | Store listing |\n|--------|----------|-----------|-----------|---------------|\n| **Re-publish (update)** | Same database, schema changes apply | Persists; all users keep their data | Unchanged | Same app, new version number |\n| **Fork** | Unchanged at fork time; you choose which database the fork uses when you publish it (the option appears if the original app was published) | Depends on the database you choose at publish time | Same ID carries over (agent can change it on request) | Same team and listing - do not submit a fork as a new app |\n\n**Re-publish:**\n- Database connection string stays the same\n- Existing collections and documents remain\n- Schema migrations (new fields, indexes) affect all app versions immediately\n- Users who haven't updated yet will query the *new* schema - plan for backward compatibility\n\n**Fork:**\n- Forking itself doesn't touch any data - the database decision comes later, when you publish the forked app\n- If the original app was published, publishing the fork asks you to choose between databases\n- Your bundle ID / package name carries over automatically\n\n<Tip>\nIf you need to selectively migrate or transform data after a fork, you can export collections and import them as needed. See the [Database (MongoDB)](/database-mongodb) page for connection details.\n</Tip>","published_title":"Database & data on mobile","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"b242a12d-d7d1-4aee-bd43-45b0e7885336","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Package name, Bundle ID & App ID","slug":"package-name-bundle-id-app-id","content":"## What are package names, bundle IDs and app IDs?\n\nEvery mobile app needs a unique identifier that distinguishes it from all other apps on the platform. These identifiers are platform-specific:\n\n- **Android package name** - a reverse-domain-style string like `com.yourcompany.appname` that uniquely identifies your app on Google Play and Android devices.\n- **iOS bundle ID** - a similar reverse-domain string (e.g. `com.yourcompany.appname`) that identifies your app in the App Store and across Apple's ecosystem.\n- **App ID** - in Apple's developer portal, the bundle ID is registered as an \"App ID\" that controls entitlements, certificates and provisioning profiles.\n\nEmergent automatically seeds these identifiers into `app.json` at environment setup, in the format `com.emergent.<words>.<suffix>`. The first-build form is pre-populated with these values and is editable before you trigger your first build. You will need to register the package name in your own Play Console.\n\n<Note title=\"Seeded at environment setup\">\nThe package name and bundle ID are seeded into `app.json` when your environment is set up, in the format `com.emergent.<words>.<suffix>`. The pre-populated first-build form lets you review and edit them before your first build is triggered.\n</Note>\n\n## Package name & bundle ID after first build\n\nOnce Emergent has published your first build, the **app name locks after first build**. Your display name remains changeable at any time. To change the Android package name, ask the agent - but if the app is already listed on the Play Store, you'll continue as a new listing. To change the iOS bundle ID, contact support.\n\n<Warning title=\"Plan your identifier before first publish\">\nChoose your app's name and branding carefully before triggering the first build. Changing the package name or bundle ID later requires creating an entirely new app listing in the stores - your existing installs, reviews and rankings will not transfer.\n</Warning>\n\n### Align integrations with the same identifier\n\nAny third-party integration you configure - Apple Music APIs, Firebase services, OAuth providers, push notification certificates - must be registered using the **exact same** bundle ID or package name that Emergent generated.\n\nIf you register an Apple Music integration under `com.example.myapp` but your iOS bundle ID is `com.example.myapp2`, the integration will fail at runtime. Always verify that external dashboards (Apple Developer, Google Cloud Console, etc.) use the identifier Emergent assigned.\n\n<Tip>\nYou can find your app's package name and bundle ID by asking the agent itself.\n</Tip>\n\n## Native mobile apps do not require a domain\n\nUnlike web apps, native iOS and Android applications do not need a custom domain to function. The app stores distribute your APK or IPA directly to users' devices; there is no URL to visit.\n\n<Info title=\"No domain purchase required\">\nYou can build, publish and distribute a mobile app on Emergent without buying or configuring a domain. If you later decide to add a companion website or [convert your app to web](/web-mobile-conversion-canonical), you can attach a [custom domain](/custom-domain) at that time.\n</Info>\n\nUniversal links (iOS) and App Links (Android) *can* use a domain to deep-link into your app, but the app itself runs independently of any web address.","order":35,"parent_id":null,"icon":"package","description":"Package name, Bundle ID & App ID","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.135343+00:00","published_at":"2026-09-24T14:08:11.135343+00:00","published_content":"## What are package names, bundle IDs and app IDs?\n\nEvery mobile app needs a unique identifier that distinguishes it from all other apps on the platform. These identifiers are platform-specific:\n\n- **Android package name** - a reverse-domain-style string like `com.yourcompany.appname` that uniquely identifies your app on Google Play and Android devices.\n- **iOS bundle ID** - a similar reverse-domain string (e.g. `com.yourcompany.appname`) that identifies your app in the App Store and across Apple's ecosystem.\n- **App ID** - in Apple's developer portal, the bundle ID is registered as an \"App ID\" that controls entitlements, certificates and provisioning profiles.\n\nEmergent automatically seeds these identifiers into `app.json` at environment setup, in the format `com.emergent.<words>.<suffix>`. The first-build form is pre-populated with these values and is editable before you trigger your first build. You will need to register the package name in your own Play Console.\n\n<Note title=\"Seeded at environment setup\">\nThe package name and bundle ID are seeded into `app.json` when your environment is set up, in the format `com.emergent.<words>.<suffix>`. The pre-populated first-build form lets you review and edit them before your first build is triggered.\n</Note>\n\n## Package name & bundle ID after first build\n\nOnce Emergent has published your first build, the **app name locks after first build**. Your display name remains changeable at any time. To change the Android package name, ask the agent - but if the app is already listed on the Play Store, you'll continue as a new listing. To change the iOS bundle ID, contact support.\n\n<Warning title=\"Plan your identifier before first publish\">\nChoose your app's name and branding carefully before triggering the first build. Changing the package name or bundle ID later requires creating an entirely new app listing in the stores - your existing installs, reviews and rankings will not transfer.\n</Warning>\n\n### Align integrations with the same identifier\n\nAny third-party integration you configure - Apple Music APIs, Firebase services, OAuth providers, push notification certificates - must be registered using the **exact same** bundle ID or package name that Emergent generated.\n\nIf you register an Apple Music integration under `com.example.myapp` but your iOS bundle ID is `com.example.myapp2`, the integration will fail at runtime. Always verify that external dashboards (Apple Developer, Google Cloud Console, etc.) use the identifier Emergent assigned.\n\n<Tip>\nYou can find your app's package name and bundle ID by asking the agent itself.\n</Tip>\n\n## Native mobile apps do not require a domain\n\nUnlike web apps, native iOS and Android applications do not need a custom domain to function. The app stores distribute your APK or IPA directly to users' devices; there is no URL to visit.\n\n<Info title=\"No domain purchase required\">\nYou can build, publish and distribute a mobile app on Emergent without buying or configuring a domain. If you later decide to add a companion website or [convert your app to web](/web-mobile-conversion-canonical), you can attach a [custom domain](/custom-domain) at that time.\n</Info>\n\nUniversal links (iOS) and App Links (Android) *can* use a domain to deep-link into your app, but the app itself runs independently of any web address.","published_title":"Package name, Bundle ID & App ID","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"3cac4fb7-4419-4a3c-9234-3e43325682c7","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing to the stores","slug":"publishing-to-the-stores","content":"## Overview\n\nPublishing your Emergent-built mobile app to the App Store and Google Play is handled through Emergent's managed build pipeline, you do not need an Expo account, the `eas-cli`, or any local build tooling. Emergent manages EAS on your behalf. This guide explains how store builds are triggered, how signing credentials work, and what you need to provide to get your app live.\n\n<Note>\nAll native builds (APK / AAB / IPA) require a **paid Emergent plan**. Builds are triggered from the Publish panel and are built from your **last published code**, fix issues, re-publish, then rebuild.\n</Note>\n\n---\n\n## Before you begin\n\nYou need two things before triggering a store build:\n\n<Steps>\n<Step title=\"Enroll in the Apple Developer Program\">\nVisit [developer.apple.com/programs](https://developer.apple.com/programs) and enroll. You cannot submit an iOS app without an active paid membership ($99/year for individuals).\n</Step>\n\n<Step title=\"Create a Google Play Console account\">\nRegister at [play.google.com/console](https://play.google.com/console). Google charges a one-time $25 registration fee. You register your app's package name here, Emergent seeds a default package name (`com.emergent.<words>.<suffix>`) into `app.json` at setup, and you can edit it in the pre-populated first-build form.\n</Step>\n</Steps>\n\n<Warning title=\"Do NOT modify eas.json\">\nEmergent manages your EAS configuration. Editing `eas.json` manually can break the build pipeline.\n</Warning>\n\n---\n\n## How builds work\n\nEmergent uses its own Expo/EAS infrastructure to produce your `.ipa` (iOS) and `.aab` (Android) binaries. You never install `eas-cli`, log in to Expo, or run builds yourself.\n\n**To trigger a native build:**\n\n<Steps>\n<Step title=\"Fix and re-publish\">\nMake sure your app is in a working state and re-publish it from the Publish panel. Builds always use the **last published code**.\n</Step>\n\n<Step title=\"Open the Publish panel\">\nNavigate to the Publish panel inside your project on **app.emergent.sh**.\n</Step>\n\n<Step title=\"Trigger the build\">\nSelect your target platform (iOS or Android) and start the build. The pipeline runs in Emergent's cloud, no Mac required for iOS.\n</Step>\n</Steps>\n\n---\n\n## iOS vs Android publishing flow\n\n| **Step** | **iOS (App Store Connect)** | **Android (Google Play Console)** |\n|----------|-----------------------------|------------------------------------|\n| **Build artifact** | `.ipa` (uploaded to testflight directly) | `.aab` Android App Bundle (produced by Emergent's pipeline) |\n| **Store listing** | Create app record in App Store Connect; add screenshots, description, support URL, privacy policy | Create app record in Play Console; add screenshots, description, privacy policy, content rating questionnaire |\n| **Compliance** | Privacy Nutrition Label (declare data collection); declare third-party SDKs | Data safety form; declare permissions; complete content rating questionnaire |\n| **Store upload** | TestFlight upload is done for you as part of the build pipeline | Upload `.aab` directly in Play Console |\n| **Review timeline** |  Apple typically reviews iOS submissions within 1-3 days. | Google Play reviews are often completed same-day but going live requires 14 days of active testing across 12 real testers |\n| **Rejection handling** | Apple provides feedback in Resolution Center; fix, re-publish, rebuild, and resubmit | Google sends email with policy violation details; fix, re-publish, rebuild, and resubmit |\n\n### Privacy & compliance\n\nBoth stores require you to disclose what data your app collects:\n\n- **iOS Privacy Nutrition Label**: In App Store Connect, declare each data type (location, contacts, analytics identifiers, etc.) and whether it is linked to the user's identity.\n- **Android Data safety**: In Play Console, complete the data safety form with similar disclosures.\n\nIf you integrate third-party SDKs (analytics, crash reporting, authentication), review their documentation for required disclosures.\n\n---\n\n## Signing credentials\n\n## Android signing\n\nIf you built your app on Emergent from the start, signing is fully handled for you: Emergent generates and holds the signing key and uses it for every build. Just click **Publish**, then **Build**, and submit the resulting `.aab` to the Play Console - there is nothing to configure.\n\nThe exception is when you **already have an app listed on the Play Store with the same package name**, signed with its own key. The new AAB won't match the listing's signing key, so the upload fails with a keystore mismatch. To resolve it, contact **support@emergent.sh** - there are two ways, and support will help you pick:\n\n- **Align Emergent to your key**: share your existing `.jks` file and keystore credentials, and Emergent updates the signing setup on our side.\n- **Align Google to Emergent's key**: Emergent provides SHA fingerprints and a `.pem` file that you upload in the Google Play Console as an upload-key reset. The Google side typically takes 2-3 business days to process.\n\n\n<Note title=\"Keep your own keystore safe\">\nIf you manage your own keystore, never commit the keystore file or its passwords to version control. If you lose your keystore, you cannot update your existing Play Store app - you would need to publish as a completely new app.\n</Note>\n\n### iOS signing\n\niOS signing is fully Emergent-managed. The App Store Connect API key is auto-created and managed by Emergent. If you need push notifications, ask the agent to set up **Emergent-managed push notifications** and share the push credentials it asks for (your APNs `.p8` push key for iOS, your Firebase service-account key for Android) before you re-publish and build - missing push credentials will cause the build to fail.  The TestFlight upload step is handled for you as part of the pipeline.\n\n---\n\n## App updates after publishing\n\nWhen you need to release a new version:\n\n<Steps>\n<Step title=\"Make your changes and re-publish\">\nFix or update your app, then re-publish from the Publish panel. Builds always use the last published code.\n</Step>\n\n<Step title=\"Trigger a new build\">\nStart a new build from the Publish panel for the target platform.\n</Step>\n\n<Step title=\"Submit to the stores\">\nFor Android, upload the new `.aab` to Play Console. If the upload fails with a keystore mismatch on an app that was on the Play Store before Emergent, see Android signing above. For iOS, the pipeline handles the TestFlight upload; you then promote the build to App Store review in App Store Connect.\n</Step>\n</Steps>\n\n<Info title=\"Every update ships through a new build\">\nEmergent does not support over-the-air updates. All changes, including JavaScript-only changes, ship by re-publishing, generating a new build, and submitting it to the stores.\n</Info>","order":36,"parent_id":null,"icon":"rocket","description":"Publishing to the stores","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.251639+00:00","published_at":"2026-09-24T14:08:11.251639+00:00","published_content":"## Overview\n\nPublishing your Emergent-built mobile app to the App Store and Google Play is handled through Emergent's managed build pipeline, you do not need an Expo account, the `eas-cli`, or any local build tooling. Emergent manages EAS on your behalf. This guide explains how store builds are triggered, how signing credentials work, and what you need to provide to get your app live.\n\n<Note>\nAll native builds (APK / AAB / IPA) require a **paid Emergent plan**. Builds are triggered from the Publish panel and are built from your **last published code**, fix issues, re-publish, then rebuild.\n</Note>\n\n---\n\n## Before you begin\n\nYou need two things before triggering a store build:\n\n<Steps>\n<Step title=\"Enroll in the Apple Developer Program\">\nVisit [developer.apple.com/programs](https://developer.apple.com/programs) and enroll. You cannot submit an iOS app without an active paid membership ($99/year for individuals).\n</Step>\n\n<Step title=\"Create a Google Play Console account\">\nRegister at [play.google.com/console](https://play.google.com/console). Google charges a one-time $25 registration fee. You register your app's package name here, Emergent seeds a default package name (`com.emergent.<words>.<suffix>`) into `app.json` at setup, and you can edit it in the pre-populated first-build form.\n</Step>\n</Steps>\n\n<Warning title=\"Do NOT modify eas.json\">\nEmergent manages your EAS configuration. Editing `eas.json` manually can break the build pipeline.\n</Warning>\n\n---\n\n## How builds work\n\nEmergent uses its own Expo/EAS infrastructure to produce your `.ipa` (iOS) and `.aab` (Android) binaries. You never install `eas-cli`, log in to Expo, or run builds yourself.\n\n**To trigger a native build:**\n\n<Steps>\n<Step title=\"Fix and re-publish\">\nMake sure your app is in a working state and re-publish it from the Publish panel. Builds always use the **last published code**.\n</Step>\n\n<Step title=\"Open the Publish panel\">\nNavigate to the Publish panel inside your project on **app.emergent.sh**.\n</Step>\n\n<Step title=\"Trigger the build\">\nSelect your target platform (iOS or Android) and start the build. The pipeline runs in Emergent's cloud, no Mac required for iOS.\n</Step>\n</Steps>\n\n---\n\n## iOS vs Android publishing flow\n\n| **Step** | **iOS (App Store Connect)** | **Android (Google Play Console)** |\n|----------|-----------------------------|------------------------------------|\n| **Build artifact** | `.ipa` (uploaded to testflight directly) | `.aab` Android App Bundle (produced by Emergent's pipeline) |\n| **Store listing** | Create app record in App Store Connect; add screenshots, description, support URL, privacy policy | Create app record in Play Console; add screenshots, description, privacy policy, content rating questionnaire |\n| **Compliance** | Privacy Nutrition Label (declare data collection); declare third-party SDKs | Data safety form; declare permissions; complete content rating questionnaire |\n| **Store upload** | TestFlight upload is done for you as part of the build pipeline | Upload `.aab` directly in Play Console |\n| **Review timeline** |  Apple typically reviews iOS submissions within 1-3 days. | Google Play reviews are often completed same-day but going live requires 14 days of active testing across 12 real testers |\n| **Rejection handling** | Apple provides feedback in Resolution Center; fix, re-publish, rebuild, and resubmit | Google sends email with policy violation details; fix, re-publish, rebuild, and resubmit |\n\n### Privacy & compliance\n\nBoth stores require you to disclose what data your app collects:\n\n- **iOS Privacy Nutrition Label**: In App Store Connect, declare each data type (location, contacts, analytics identifiers, etc.) and whether it is linked to the user's identity.\n- **Android Data safety**: In Play Console, complete the data safety form with similar disclosures.\n\nIf you integrate third-party SDKs (analytics, crash reporting, authentication), review their documentation for required disclosures.\n\n---\n\n## Signing credentials\n\n## Android signing\n\nIf you built your app on Emergent from the start, signing is fully handled for you: Emergent generates and holds the signing key and uses it for every build. Just click **Publish**, then **Build**, and submit the resulting `.aab` to the Play Console - there is nothing to configure.\n\nThe exception is when you **already have an app listed on the Play Store with the same package name**, signed with its own key. The new AAB won't match the listing's signing key, so the upload fails with a keystore mismatch. To resolve it, contact **support@emergent.sh** - there are two ways, and support will help you pick:\n\n- **Align Emergent to your key**: share your existing `.jks` file and keystore credentials, and Emergent updates the signing setup on our side.\n- **Align Google to Emergent's key**: Emergent provides SHA fingerprints and a `.pem` file that you upload in the Google Play Console as an upload-key reset. The Google side typically takes 2-3 business days to process.\n\n\n<Note title=\"Keep your own keystore safe\">\nIf you manage your own keystore, never commit the keystore file or its passwords to version control. If you lose your keystore, you cannot update your existing Play Store app - you would need to publish as a completely new app.\n</Note>\n\n### iOS signing\n\niOS signing is fully Emergent-managed. The App Store Connect API key is auto-created and managed by Emergent. If you need push notifications, ask the agent to set up **Emergent-managed push notifications** and share the push credentials it asks for (your APNs `.p8` push key for iOS, your Firebase service-account key for Android) before you re-publish and build - missing push credentials will cause the build to fail.  The TestFlight upload step is handled for you as part of the pipeline.\n\n---\n\n## App updates after publishing\n\nWhen you need to release a new version:\n\n<Steps>\n<Step title=\"Make your changes and re-publish\">\nFix or update your app, then re-publish from the Publish panel. Builds always use the last published code.\n</Step>\n\n<Step title=\"Trigger a new build\">\nStart a new build from the Publish panel for the target platform.\n</Step>\n\n<Step title=\"Submit to the stores\">\nFor Android, upload the new `.aab` to Play Console. If the upload fails with a keystore mismatch on an app that was on the Play Store before Emergent, see Android signing above. For iOS, the pipeline handles the TestFlight upload; you then promote the build to App Store review in App Store Connect.\n</Step>\n</Steps>\n\n<Info title=\"Every update ships through a new build\">\nEmergent does not support over-the-air updates. All changes, including JavaScript-only changes, ship by re-publishing, generating a new build, and submitting it to the stores.\n</Info>","published_title":"Publishing to the stores","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"4059cdcc-3537-4efc-95cd-4e0adc867d69","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Monetisation: in-app purchases & subscriptions","slug":"monetisation-in-app-purchases-subscriptions","content":"## Overview\n\nEmergent supports **native in-app purchases** (IAP) and **subscriptions** for both iOS and Android, letting you monetise mobile apps with minimal setup. Revenue flows through Apple App Store and Google Play Store, with platform fees deducted automatically.\n\nFor cross-platform subscription management and entitlement sync, Emergent integrates **RevenueCat**. For direct payment links in India, you can use **Razorpay** web checkout flows.\n\n---\n\n## Platform fees & revenue share\n\n<Note>\nApple and Google collect their fees directly from customer payments before remitting revenue to your developer account.\n</Note>\n\n| Store | Standard rate | Small Business rate | Eligibility |\n|-------|---------------|---------------------|-------------|\n| **Apple App Store** | 30% | 15% | Developers earning <$1M/year across all apps |\n| **Google Play** | 15-30% by revenue tier | | Varies by revenue tier |\n\n---\n\n## Apple In-App Purchase (IAP)\n\n### How it works\n\n1. Define consumable, non-consumable or auto-renewable subscription products in **App Store Connect**.\n2. Your agent can wire up product IDs and purchase flows using RevenueCat.\n3. Receipts are validated server-side to unlock entitlements.\n\n<Steps>\n<Step title=\"Create IAP products in App Store Connect\">\nLog into [App Store Connect](https://appstoreconnect.apple.com/) → **My Apps** → your app → **In-App Purchases** → **+**. Configure product ID, pricing and localisations.\n</Step>\n\n<Step title=\"Add product IDs to your Emergent project\">\nTell your agent which product IDs to implement (e.g. `premium_monthly`, `coins_100`). The agent will generate the purchase code and UI.\n</Step>\n\n<Step title=\"Test with sandbox accounts\">\nCreate sandbox test users in App Store Connect → **Users and Access** → **Sandbox Testers**. Sign in with that account on your test device to trial purchases without real charges.\n</Step>\n\n<Step title=\"Validate receipts server-side\">\nYour Emergent backend verifies receipts with Apple's validation API and grants entitlements in your [database](/database-mongodb).\n</Step>\n</Steps>\n\n<Warning title=\"Sandbox vs production receipts\">\nApple issues different receipt signatures for sandbox and production. Your validation logic must target the correct endpoint (`buy.itunes.apple.com` for production, `sandbox.itunes.apple.com` for testing).\n</Warning>\n\n---\n\n## Google Play Billing\n\n### How it works\n\nGoogle Play Billing works similarly: define products in the Play Console, integrate the Billing Library in your Android app, and validate purchases server-side via the Play Developer API.\n\n<Steps>\n<Step title=\"Set up products in Google Play Console\">\n**Monetize** → **Products** → **Create product**. Choose one-time, consumable or subscription, assign a SKU and set pricing.\n</Step>\n\n<Step title=\"Integrate Play Billing Library\">\nDescribe the purchase flow to your agent (e.g. \"Show a paywall for `premium_yearly`\") and it will wire up the billing integration.\n</Step>\n\n<Step title=\"Test with license testers\">\nAdd test Google accounts under **Setup** → **License Testing** in the Play Console. These accounts can make real purchase flows that don't charge a card.\n</Step>\n\n<Step title=\"Verify purchase tokens\">\nAfter a successful purchase, send the token to your backend. Call the [Play Developer API](https://developers.google.com/android-publisher) to confirm validity and grant access.\n</Step>\n</Steps>\n\n<Tip>\nEnable **real-time developer notifications** (RTDN) in the Play Console to receive webhook events when subscriptions renew, cancel or expire.\n</Tip>\n\n---\n\n## Cross-platform entitlements with RevenueCat\n\n**RevenueCat** is a third-party service that unifies IAP logic across iOS, Android and web. It handles receipt validation, webhook delivery, and customer entitlement state - so you query one API instead of maintaining separate Apple and Google integrations.\n\n### Why use RevenueCat?\n\n<CardGroup cols={2}>\n<Card title=\"Single source of truth\" icon=\"database\">\nCheck a user's subscription status with one REST call, regardless of which store they purchased from.\n</Card>\n\n<Card title=\"Webhooks for lifecycle events\" icon=\"bell\">\nReceive real-time notifications on purchase, renewal, cancellation, refund or billing issue.\n</Card>\n\n<Card title=\"Paywall experiments\" icon=\"flask\">\nA/B test pricing and messaging without app updates (requires RevenueCat Paywalls SDK).\n</Card>\n\n<Card title=\"Analytics & churn metrics\" icon=\"chart-line\">\nBuilt-in dashboard for MRR, LTV, churn cohorts and trial conversion.\n</Card>\n</CardGroup>\n\n### Integration steps\n\n<Steps>\n<Step title=\"Create a RevenueCat account\">\nSign up at [revenuecat.com](https://www.revenuecat.com/) and create a new project.\n</Step>\n\n<Step title=\"Add platform credentials\">\nUnder **Project Settings**, upload your Apple Shared Secret (from App Store Connect) and Google Service Account JSON (from Play Console → API access).\n</Step>\n\n<Step title=\"Define entitlements\">\nIn the RevenueCat dashboard, create entitlements like `premium` or `pro` and map your App Store / Play Store product IDs to them.\n</Step>\n\n<Step title=\"Add RevenueCat from the Connectors panel\">\nOpen your app's **Preview**, click **Manage** (to the right of Preview), then open the **Connectors** tab. Find the **RevenueCat** tile and click **Add**, then follow the prompts to connect your RevenueCat project. The platform wires the SDK into your app and stores your API key securely.\n</Step>\n\n<Step title=\"Check entitlements in your app\">\nCall `Purchases.shared.getCustomerInfo()` (iOS) or `Purchases.sharedInstance.customerInfo` (Android) to see which entitlements the user has. Your backend can also query the [REST API](https://www.revenuecat.com/docs/api-v1) if you prefer server-side checks.\n</Step>\n</Steps>\n\n<Info>\nRevenueCat's free tier supports up to **$2.5k monthly tracked revenue**. Beyond that, pricing is 1% of tracked revenue. See [RevenueCat pricing](https://www.revenuecat.com/pricing/) for details.\n</Info>\n\n---\n\n## Razorpay payment links for India\n\nFor **web-based checkout flows** or payment links (particularly useful in India), you can integrate [Razorpay](/razorpay).\n\n<Note>\nRazorpay checkout is a **web experience** - best for one-time purchases, donations or manual top-ups. For recurring mobile subscriptions tied to app store accounts, use Apple IAP or Google Play Billing instead.\n</Note>\n\n### When to use Razorpay\n\n- **Direct payment links**: Send a customer a Razorpay link via SMS, email or in-app browser.\n- **UPI, cards, wallets**: Support popular Indian payment methods outside the app stores.\n- **Lower fees**: Razorpay charges fees that are lower than app store rates (but you lose the store's trust signals and one-tap purchase UX).\n\n### How to add it\n\n<Steps>\n<Step title=\"Open the Connectors panel\">\nOpen your app's **Preview**, click **Manage** (to the right of Preview), then open the **Connectors** tab.\n</Step>\n\n<Step title=\"Add the Razorpay connector\">\nFind the **Razorpay** tile and click **Add**, then follow the prompts to connect your Razorpay account.\n</Step>\n</Steps>\n\nSee the [Razorpay](/razorpay) page for going live and webhook handling.\n\n---\n\n---\n\n## Compliance & policies\n\n<Warning title=\"App store review guidelines\">\nBoth Apple and Google prohibit **alternative payment mechanisms for digital goods (e.g. coins, premium features) sold inside the app. You must** use IAP/Play Billing for such items. Razorpay links are only acceptable for physical goods, services or donations.\n</Warning>\n\n<AccordionGroup>\n<Accordion title=\"Can I offer a cheaper subscription on my website?\">\nYes, but you cannot advertise or link to it from the iOS/Android app (Apple/Google rules). Users who find your site independently can subscribe there, then sign in to the app to unlock features.\n</Accordion>\n\n<Accordion title=\"What about promotional codes?\">\nBoth stores support **promo codes** (Apple: Offer Codes; Google: Promo Codes). Generate them in the respective console and distribute via email, social media or influencer partnerships.\n</Accordion>\n\n<Accordion title=\"How do refunds work?\">\nApple and Google handle refunds directly. You'll receive a webhook (or RTDN) event when a refund is issued; revoke the user's entitlement in your database at that point.\n</Accordion>\n\n<Accordion title=\"Can I use Stripe for mobile subscriptions?\">\nStripe is hidden on Expo/React Native projects in Emergent (Razorpay and PayPal remain available). For digital content or features unlocked in the app, you must use native IAP regardless of payment provider.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Testing purchases without spending money\n\n<Tabs>\n<Tab title=\"iOS Sandbox\">\nCreate **sandbox test accounts** in App Store Connect → **Users and Access** → **Sandbox Testers**. Sign in with that Apple ID on your device (Settings → App Store → Sandbox Account) to make test purchases that don't charge a real card.\n</Tab>\n\n<Tab title=\"Android License Testing\">\nAdd your Google account email under **Play Console** → **Setup** → **License Testing**. Purchases made by that account will complete instantly without payment.\n</Tab>\n\n<Tab title=\"RevenueCat\">\nRevenueCat mirrors sandbox/test purchases in its dashboard. You'll see test transactions labelled as **sandbox** so you can verify entitlement logic before going live.\n</Tab>\n</Tabs>\n\n<Tip title=\"Accelerated renewals in sandbox\">\nApple's sandbox compresses subscription durations: a one-month subscription renews every **5 minutes**. This lets you test renewal, expiry and grace-period logic quickly.\n</Tip>\n\n---\n\n## Best practices\n\n1. **Show clear pricing and terms** before the purchase sheet appears - both stores require transparency.\n2. **Handle pending transactions**: A purchase can be interrupted (user switches apps, loses connectivity). Resume the transaction flow on next launch.\n3. **Log all purchase events**: Store receipts and transaction IDs in your [database](/database-mongodb) for audit trails and customer support.\n4. **Offer a restore-purchases button**: Users who reinstall or switch devices need a way to re-validate their entitlements.\n5. **Monitor failed renewals**: Set up webhooks (RevenueCat or native RTDN) to catch billing issues and prompt users to update payment info.\n\n<Success title=\"Ready to monetise\">\nWith native IAP, RevenueCat entitlements and optional Razorpay links, you have flexible monetisation options for any mobile app. Ask your Emergent agent to implement the purchase flow that fits your business model.\n</Success>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Razorpay\" icon=\"credit-card\" href=\"/razorpay\">\nSet up direct payment links for India (UPI, cards, wallets).\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nStore user entitlements, purchase history and subscription state.\n</Card>\n\n<Card title=\"Web to Mobile conversion\" icon=\"arrows-rotate\" href=\"/web-mobile-conversion-canonical\">\nUnderstand how Emergent adapts your app for web and mobile platforms.\n</Card>\n\n<Card title=\"App takedown & content moderation\" icon=\"gavel\" href=\"/app-takedown-content-moderation\">\nPolicies and procedures if your app faces a store violation.\n</Card>\n</CardGroup>","order":37,"parent_id":null,"icon":"tag","description":"Monetise mobile apps via Apple IAP (30%/15% fees), Google Play Billing, cross-platform entitlements through RevenueCat, and Razorpay links for India.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.146684+00:00","published_at":"2026-09-24T14:08:11.146684+00:00","published_content":"## Overview\n\nEmergent supports **native in-app purchases** (IAP) and **subscriptions** for both iOS and Android, letting you monetise mobile apps with minimal setup. Revenue flows through Apple App Store and Google Play Store, with platform fees deducted automatically.\n\nFor cross-platform subscription management and entitlement sync, Emergent integrates **RevenueCat**. For direct payment links in India, you can use **Razorpay** web checkout flows.\n\n---\n\n## Platform fees & revenue share\n\n<Note>\nApple and Google collect their fees directly from customer payments before remitting revenue to your developer account.\n</Note>\n\n| Store | Standard rate | Small Business rate | Eligibility |\n|-------|---------------|---------------------|-------------|\n| **Apple App Store** | 30% | 15% | Developers earning <$1M/year across all apps |\n| **Google Play** | 15-30% by revenue tier | | Varies by revenue tier |\n\n---\n\n## Apple In-App Purchase (IAP)\n\n### How it works\n\n1. Define consumable, non-consumable or auto-renewable subscription products in **App Store Connect**.\n2. Your agent can wire up product IDs and purchase flows using RevenueCat.\n3. Receipts are validated server-side to unlock entitlements.\n\n<Steps>\n<Step title=\"Create IAP products in App Store Connect\">\nLog into [App Store Connect](https://appstoreconnect.apple.com/) → **My Apps** → your app → **In-App Purchases** → **+**. Configure product ID, pricing and localisations.\n</Step>\n\n<Step title=\"Add product IDs to your Emergent project\">\nTell your agent which product IDs to implement (e.g. `premium_monthly`, `coins_100`). The agent will generate the purchase code and UI.\n</Step>\n\n<Step title=\"Test with sandbox accounts\">\nCreate sandbox test users in App Store Connect → **Users and Access** → **Sandbox Testers**. Sign in with that account on your test device to trial purchases without real charges.\n</Step>\n\n<Step title=\"Validate receipts server-side\">\nYour Emergent backend verifies receipts with Apple's validation API and grants entitlements in your [database](/database-mongodb).\n</Step>\n</Steps>\n\n<Warning title=\"Sandbox vs production receipts\">\nApple issues different receipt signatures for sandbox and production. Your validation logic must target the correct endpoint (`buy.itunes.apple.com` for production, `sandbox.itunes.apple.com` for testing).\n</Warning>\n\n---\n\n## Google Play Billing\n\n### How it works\n\nGoogle Play Billing works similarly: define products in the Play Console, integrate the Billing Library in your Android app, and validate purchases server-side via the Play Developer API.\n\n<Steps>\n<Step title=\"Set up products in Google Play Console\">\n**Monetize** → **Products** → **Create product**. Choose one-time, consumable or subscription, assign a SKU and set pricing.\n</Step>\n\n<Step title=\"Integrate Play Billing Library\">\nDescribe the purchase flow to your agent (e.g. \"Show a paywall for `premium_yearly`\") and it will wire up the billing integration.\n</Step>\n\n<Step title=\"Test with license testers\">\nAdd test Google accounts under **Setup** → **License Testing** in the Play Console. These accounts can make real purchase flows that don't charge a card.\n</Step>\n\n<Step title=\"Verify purchase tokens\">\nAfter a successful purchase, send the token to your backend. Call the [Play Developer API](https://developers.google.com/android-publisher) to confirm validity and grant access.\n</Step>\n</Steps>\n\n<Tip>\nEnable **real-time developer notifications** (RTDN) in the Play Console to receive webhook events when subscriptions renew, cancel or expire.\n</Tip>\n\n---\n\n## Cross-platform entitlements with RevenueCat\n\n**RevenueCat** is a third-party service that unifies IAP logic across iOS, Android and web. It handles receipt validation, webhook delivery, and customer entitlement state - so you query one API instead of maintaining separate Apple and Google integrations.\n\n### Why use RevenueCat?\n\n<CardGroup cols={2}>\n<Card title=\"Single source of truth\" icon=\"database\">\nCheck a user's subscription status with one REST call, regardless of which store they purchased from.\n</Card>\n\n<Card title=\"Webhooks for lifecycle events\" icon=\"bell\">\nReceive real-time notifications on purchase, renewal, cancellation, refund or billing issue.\n</Card>\n\n<Card title=\"Paywall experiments\" icon=\"flask\">\nA/B test pricing and messaging without app updates (requires RevenueCat Paywalls SDK).\n</Card>\n\n<Card title=\"Analytics & churn metrics\" icon=\"chart-line\">\nBuilt-in dashboard for MRR, LTV, churn cohorts and trial conversion.\n</Card>\n</CardGroup>\n\n### Integration steps\n\n<Steps>\n<Step title=\"Create a RevenueCat account\">\nSign up at [revenuecat.com](https://www.revenuecat.com/) and create a new project.\n</Step>\n\n<Step title=\"Add platform credentials\">\nUnder **Project Settings**, upload your Apple Shared Secret (from App Store Connect) and Google Service Account JSON (from Play Console → API access).\n</Step>\n\n<Step title=\"Define entitlements\">\nIn the RevenueCat dashboard, create entitlements like `premium` or `pro` and map your App Store / Play Store product IDs to them.\n</Step>\n\n<Step title=\"Add RevenueCat from the Connectors panel\">\nOpen your app's **Preview**, click **Manage** (to the right of Preview), then open the **Connectors** tab. Find the **RevenueCat** tile and click **Add**, then follow the prompts to connect your RevenueCat project. The platform wires the SDK into your app and stores your API key securely.\n</Step>\n\n<Step title=\"Check entitlements in your app\">\nCall `Purchases.shared.getCustomerInfo()` (iOS) or `Purchases.sharedInstance.customerInfo` (Android) to see which entitlements the user has. Your backend can also query the [REST API](https://www.revenuecat.com/docs/api-v1) if you prefer server-side checks.\n</Step>\n</Steps>\n\n<Info>\nRevenueCat's free tier supports up to **$2.5k monthly tracked revenue**. Beyond that, pricing is 1% of tracked revenue. See [RevenueCat pricing](https://www.revenuecat.com/pricing/) for details.\n</Info>\n\n---\n\n## Razorpay payment links for India\n\nFor **web-based checkout flows** or payment links (particularly useful in India), you can integrate [Razorpay](/razorpay).\n\n<Note>\nRazorpay checkout is a **web experience** - best for one-time purchases, donations or manual top-ups. For recurring mobile subscriptions tied to app store accounts, use Apple IAP or Google Play Billing instead.\n</Note>\n\n### When to use Razorpay\n\n- **Direct payment links**: Send a customer a Razorpay link via SMS, email or in-app browser.\n- **UPI, cards, wallets**: Support popular Indian payment methods outside the app stores.\n- **Lower fees**: Razorpay charges fees that are lower than app store rates (but you lose the store's trust signals and one-tap purchase UX).\n\n### How to add it\n\n<Steps>\n<Step title=\"Open the Connectors panel\">\nOpen your app's **Preview**, click **Manage** (to the right of Preview), then open the **Connectors** tab.\n</Step>\n\n<Step title=\"Add the Razorpay connector\">\nFind the **Razorpay** tile and click **Add**, then follow the prompts to connect your Razorpay account.\n</Step>\n</Steps>\n\nSee the [Razorpay](/razorpay) page for going live and webhook handling.\n\n---\n\n---\n\n## Compliance & policies\n\n<Warning title=\"App store review guidelines\">\nBoth Apple and Google prohibit **alternative payment mechanisms for digital goods (e.g. coins, premium features) sold inside the app. You must** use IAP/Play Billing for such items. Razorpay links are only acceptable for physical goods, services or donations.\n</Warning>\n\n<AccordionGroup>\n<Accordion title=\"Can I offer a cheaper subscription on my website?\">\nYes, but you cannot advertise or link to it from the iOS/Android app (Apple/Google rules). Users who find your site independently can subscribe there, then sign in to the app to unlock features.\n</Accordion>\n\n<Accordion title=\"What about promotional codes?\">\nBoth stores support **promo codes** (Apple: Offer Codes; Google: Promo Codes). Generate them in the respective console and distribute via email, social media or influencer partnerships.\n</Accordion>\n\n<Accordion title=\"How do refunds work?\">\nApple and Google handle refunds directly. You'll receive a webhook (or RTDN) event when a refund is issued; revoke the user's entitlement in your database at that point.\n</Accordion>\n\n<Accordion title=\"Can I use Stripe for mobile subscriptions?\">\nStripe is hidden on Expo/React Native projects in Emergent (Razorpay and PayPal remain available). For digital content or features unlocked in the app, you must use native IAP regardless of payment provider.\n</Accordion>\n</AccordionGroup>\n\n---\n\n## Testing purchases without spending money\n\n<Tabs>\n<Tab title=\"iOS Sandbox\">\nCreate **sandbox test accounts** in App Store Connect → **Users and Access** → **Sandbox Testers**. Sign in with that Apple ID on your device (Settings → App Store → Sandbox Account) to make test purchases that don't charge a real card.\n</Tab>\n\n<Tab title=\"Android License Testing\">\nAdd your Google account email under **Play Console** → **Setup** → **License Testing**. Purchases made by that account will complete instantly without payment.\n</Tab>\n\n<Tab title=\"RevenueCat\">\nRevenueCat mirrors sandbox/test purchases in its dashboard. You'll see test transactions labelled as **sandbox** so you can verify entitlement logic before going live.\n</Tab>\n</Tabs>\n\n<Tip title=\"Accelerated renewals in sandbox\">\nApple's sandbox compresses subscription durations: a one-month subscription renews every **5 minutes**. This lets you test renewal, expiry and grace-period logic quickly.\n</Tip>\n\n---\n\n## Best practices\n\n1. **Show clear pricing and terms** before the purchase sheet appears - both stores require transparency.\n2. **Handle pending transactions**: A purchase can be interrupted (user switches apps, loses connectivity). Resume the transaction flow on next launch.\n3. **Log all purchase events**: Store receipts and transaction IDs in your [database](/database-mongodb) for audit trails and customer support.\n4. **Offer a restore-purchases button**: Users who reinstall or switch devices need a way to re-validate their entitlements.\n5. **Monitor failed renewals**: Set up webhooks (RevenueCat or native RTDN) to catch billing issues and prompt users to update payment info.\n\n<Success title=\"Ready to monetise\">\nWith native IAP, RevenueCat entitlements and optional Razorpay links, you have flexible monetisation options for any mobile app. Ask your Emergent agent to implement the purchase flow that fits your business model.\n</Success>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Razorpay\" icon=\"credit-card\" href=\"/razorpay\">\nSet up direct payment links for India (UPI, cards, wallets).\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nStore user entitlements, purchase history and subscription state.\n</Card>\n\n<Card title=\"Web to Mobile conversion\" icon=\"arrows-rotate\" href=\"/web-mobile-conversion-canonical\">\nUnderstand how Emergent adapts your app for web and mobile platforms.\n</Card>\n\n<Card title=\"App takedown & content moderation\" icon=\"gavel\" href=\"/app-takedown-content-moderation\">\nPolicies and procedures if your app faces a store violation.\n</Card>\n</CardGroup>","published_title":"Monetisation: in-app purchases & subscriptions","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"05c5ea0e-719d-4d2a-9e5a-2c4f8c5d8bf8","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Push notifications","slug":"push-notifications","content":"## Push notifications in Emergent\n\nPush notifications appear in two contexts on Emergent: **system notifications that keep you informed about your workspace, and in-app notifications** you can enable for the mobile applications you build.\n\n---\n\n## Emergent platform notifications\n\nEmergent sends push notifications to your account when important events occur:\n\n- **Published app complete** - your app shipped to production, with a deep link directly to the live URL.\n- **Credit balance low** - reminder when your [credit balance](/managing-credit-usage) falls below a threshold.\n- **Agent milestones** - when an AI agent finishes a complex build, encounters a blocker, or requests clarification.\n\n<Note>\nPlatform push notifications arrive via browser notifications if you've granted permission, or via the Emergent mobile app if available (the Emergent native mobile app is currently not distributed on the App Store/Play Store). Deep links open the relevant workspace or chat thread.\n</Note>\n\nAll platform notifications respect your account notification preferences. You can mute categories or adjust delivery hours in **Settings → Notifications**.\n\n---\n\n## Enabling push for apps you build\n\nWhen you describe a mobile app in chat, agents can integrate push notifications using **SuprSend**, a unified notification service that handles iOS (APNs) and Android (FCM) delivery.\n\n<Steps>\n\n<Step title=\"Request push in your app specification\">\nIn chat, describe the notification use case - for example:\n\n> \"Send a push when a new message arrives\"\n> \"Notify users 24 hours before their event\"\n\nThe agent will build the SuprSend integration into your Python (FastAPI) backend and React Native mobile client.\n</Step>\n\n<Step title=\"Provide Firebase credentials (Android)\">\nTo send Android push, the agent needs a Firebase Cloud Messaging service account:\n\n1. Open your [Firebase Console](https://console.firebase.google.com/).\n2. Select your project (or create one).\n3. Navigate to **Project settings → Service accounts**.\n4. Click **Generate new private key** and download the JSON file. The key must be for the same bundle ID as your project's Android bundle ID.\n5. Upload `service-account.json` at build time in the build config when prompted.\n\n<Warning>\nThe service-account key grants full Firebase access. Never commit it to a public repository. Emergent encrypts uploaded credentials at rest.\n</Warning>\n</Step>\n\n<Step title=\"Provide APNs credentials (iOS)\">\nFor iOS push, you need an Apple Push Notification service (APNs) key:\n\n1. Sign in to [Apple Developer](https://developer.apple.com/account/resources/authkeys/list).\n2. Create a new key with the **Apple Push Notifications service (APNs)** capability enabled.\n3. Download the `.p8` file (you can only download it once).\n4. Note the **Key ID** and your **Team ID** (found in your Apple Developer account membership details).\n5. Upload the `.p8` file, Key ID, and Team ID at build time in the build config. Missing push credentials will fail the build.\n\n<Info>\nA single APNs key can serve all your apps under the same Team ID. You do not need a separate key per app.\n</Info>\n</Step>\n\n<Step title=\"Test and publish\">\nOnce credentials are uploaded, the agent configures SuprSend in your backend and wires the mobile client to request push permissions on first launch.\n\nPublish your app normally via chat. The agent will confirm push is live and may send a test notification to verify delivery.\n</Step>\n\n</Steps>\n\n---\n\n## How SuprSend works in your app\n\nBehind the scenes, Emergent agents:\n\n- Add the **SuprSend SDK** to your backend API and React Native project.\n- Store device tokens securely in your [MongoDB database](/database-mongodb).\n- Trigger notifications via SuprSend's REST API from your backend workflows (cron jobs, webhooks, user actions).\n- Handle token refresh, badge counts, and deep-link routing automatically.\n\nYou can extend notification logic by describing new triggers in chat - for example, \"Send a reminder push every morning at 9 AM.\"\n\n---\n\n## Credentials security\n\n<CardGroup cols={2}>\n\n<Card title=\"Encryption at rest\" icon=\"lock\">\nFirebase and APNs keys are encrypted in Emergent's secret store and never logged or exposed in build artifacts.\n</Card>\n\n<Card title=\"Rotation & revocation\" icon=\"rotate-cw\">\n\nThere is no self-serve flow for rotating push credentials yet. If your credentials change, contact support to update them.\n</Card>\n\n</CardGroup>\n\nIf a credential is compromised, regenerate it in Firebase or Apple Developer, then contact support to update it on your app.\n\n---\n\n## Troubleshooting\n\n<AccordionGroup>\n\n<Accordion title=\"Push works on Android but not iOS\">\nVerify that:\n\n- The `.p8` key, Key ID, and Team ID match exactly.\n- You've tested on a physical device (push does not work in the iOS Simulator or in Expo Go).\n- The device has granted notification permissions (check Settings → Notifications).\n\nIf all credentials are correct but iOS push still fails, ask the agent to check the APNs configuration on the Emergent side. Note that the agent has no visibility into your SuprSend account. \n</Accordion>\n\n<Accordion title=\"Firebase service account upload fails\">\nEnsure the JSON file is valid and contains the `project_id`, `private_key`, and `client_email` fields. Re-download from Firebase Console if the file appears truncated.\n</Accordion>\n\n<Accordion title=\"Notifications deliver late or not at all\">\nSuprSend batches and retries deliveries, so slight delays are normal. If notifications never arrive:\n\n- Confirm the device token was successfully registered (check your MongoDB `devices` collection).\n- Verify the user granted notification permissions at the OS level.\n</Accordion>\n\n<Accordion title=\"Can I use a different push provider?\">\nYes. Describe your preferred service in chat (for example, OneSignal, Pusher Beams, or a custom APNs/FCM integration). The agent can swap providers, though SuprSend is the default because it unifies iOS and Android with minimal setup.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Deep links in notifications\n\nBoth Emergent platform notifications and your app's push messages support **deep links** - tapping a notification opens a specific screen or resource:\n\n- **Platform notifications** deep-link into the Emergent workspace (for example, directly to a chat thread or published app dashboard).\n- **Your app's notifications** can deep-link to any screen you define. Describe the link structure in chat:\n\n > \"When a user taps the new-message push, open the chat screen with `conversationId` pre-filled.\"\n\nThe agent will configure URL schemes (iOS) and intent filters (Android) automatically.\n\n<Tip>\nDeep links dramatically improve engagement.\n\nUsers who tap a notification convert at 3-5× the rate of users who open the app cold.\n</Tip>\n\n---\n\n## Related topics\n\n<CardGroup cols={2}>\n\n<Card title=\"Emergent Auth\" icon=\"shield-check\" href=\"/emergent-auth-built-in\">\nHow user authentication integrates with device-token registration for push.\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nWhere device tokens and notification state are stored.\n</Card>\n\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nDeep links work smoothly with your custom domain once configured.\n</Card>\n\n<Card title=\"Managing credit usage\" icon=\"credit-card\" href=\"/managing-credit-usage\">\nUnderstand when Emergent sends you low-balance push alerts.\n</Card>\n\n</CardGroup>","order":38,"parent_id":null,"icon":"file-text","description":"Push for the Emergent app itself (deploy/credit/agent alerts with deep links) and enabling push in apps you build via SuprSend (Android service-account.json, iOS .p8).","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.235533+00:00","published_at":"2026-09-24T14:08:11.235533+00:00","published_content":"## Push notifications in Emergent\n\nPush notifications appear in two contexts on Emergent: **system notifications that keep you informed about your workspace, and in-app notifications** you can enable for the mobile applications you build.\n\n---\n\n## Emergent platform notifications\n\nEmergent sends push notifications to your account when important events occur:\n\n- **Published app complete** - your app shipped to production, with a deep link directly to the live URL.\n- **Credit balance low** - reminder when your [credit balance](/managing-credit-usage) falls below a threshold.\n- **Agent milestones** - when an AI agent finishes a complex build, encounters a blocker, or requests clarification.\n\n<Note>\nPlatform push notifications arrive via browser notifications if you've granted permission, or via the Emergent mobile app if available (the Emergent native mobile app is currently not distributed on the App Store/Play Store). Deep links open the relevant workspace or chat thread.\n</Note>\n\nAll platform notifications respect your account notification preferences. You can mute categories or adjust delivery hours in **Settings → Notifications**.\n\n---\n\n## Enabling push for apps you build\n\nWhen you describe a mobile app in chat, agents can integrate push notifications using **SuprSend**, a unified notification service that handles iOS (APNs) and Android (FCM) delivery.\n\n<Steps>\n\n<Step title=\"Request push in your app specification\">\nIn chat, describe the notification use case - for example:\n\n> \"Send a push when a new message arrives\"\n> \"Notify users 24 hours before their event\"\n\nThe agent will build the SuprSend integration into your Python (FastAPI) backend and React Native mobile client.\n</Step>\n\n<Step title=\"Provide Firebase credentials (Android)\">\nTo send Android push, the agent needs a Firebase Cloud Messaging service account:\n\n1. Open your [Firebase Console](https://console.firebase.google.com/).\n2. Select your project (or create one).\n3. Navigate to **Project settings → Service accounts**.\n4. Click **Generate new private key** and download the JSON file. The key must be for the same bundle ID as your project's Android bundle ID.\n5. Upload `service-account.json` at build time in the build config when prompted.\n\n<Warning>\nThe service-account key grants full Firebase access. Never commit it to a public repository. Emergent encrypts uploaded credentials at rest.\n</Warning>\n</Step>\n\n<Step title=\"Provide APNs credentials (iOS)\">\nFor iOS push, you need an Apple Push Notification service (APNs) key:\n\n1. Sign in to [Apple Developer](https://developer.apple.com/account/resources/authkeys/list).\n2. Create a new key with the **Apple Push Notifications service (APNs)** capability enabled.\n3. Download the `.p8` file (you can only download it once).\n4. Note the **Key ID** and your **Team ID** (found in your Apple Developer account membership details).\n5. Upload the `.p8` file, Key ID, and Team ID at build time in the build config. Missing push credentials will fail the build.\n\n<Info>\nA single APNs key can serve all your apps under the same Team ID. You do not need a separate key per app.\n</Info>\n</Step>\n\n<Step title=\"Test and publish\">\nOnce credentials are uploaded, the agent configures SuprSend in your backend and wires the mobile client to request push permissions on first launch.\n\nPublish your app normally via chat. The agent will confirm push is live and may send a test notification to verify delivery.\n</Step>\n\n</Steps>\n\n---\n\n## How SuprSend works in your app\n\nBehind the scenes, Emergent agents:\n\n- Add the **SuprSend SDK** to your backend API and React Native project.\n- Store device tokens securely in your [MongoDB database](/database-mongodb).\n- Trigger notifications via SuprSend's REST API from your backend workflows (cron jobs, webhooks, user actions).\n- Handle token refresh, badge counts, and deep-link routing automatically.\n\nYou can extend notification logic by describing new triggers in chat - for example, \"Send a reminder push every morning at 9 AM.\"\n\n---\n\n## Credentials security\n\n<CardGroup cols={2}>\n\n<Card title=\"Encryption at rest\" icon=\"lock\">\nFirebase and APNs keys are encrypted in Emergent's secret store and never logged or exposed in build artifacts.\n</Card>\n\n<Card title=\"Rotation & revocation\" icon=\"rotate-cw\">\n\nThere is no self-serve flow for rotating push credentials yet. If your credentials change, contact support to update them.\n</Card>\n\n</CardGroup>\n\nIf a credential is compromised, regenerate it in Firebase or Apple Developer, then contact support to update it on your app.\n\n---\n\n## Troubleshooting\n\n<AccordionGroup>\n\n<Accordion title=\"Push works on Android but not iOS\">\nVerify that:\n\n- The `.p8` key, Key ID, and Team ID match exactly.\n- You've tested on a physical device (push does not work in the iOS Simulator or in Expo Go).\n- The device has granted notification permissions (check Settings → Notifications).\n\nIf all credentials are correct but iOS push still fails, ask the agent to check the APNs configuration on the Emergent side. Note that the agent has no visibility into your SuprSend account. \n</Accordion>\n\n<Accordion title=\"Firebase service account upload fails\">\nEnsure the JSON file is valid and contains the `project_id`, `private_key`, and `client_email` fields. Re-download from Firebase Console if the file appears truncated.\n</Accordion>\n\n<Accordion title=\"Notifications deliver late or not at all\">\nSuprSend batches and retries deliveries, so slight delays are normal. If notifications never arrive:\n\n- Confirm the device token was successfully registered (check your MongoDB `devices` collection).\n- Verify the user granted notification permissions at the OS level.\n</Accordion>\n\n<Accordion title=\"Can I use a different push provider?\">\nYes. Describe your preferred service in chat (for example, OneSignal, Pusher Beams, or a custom APNs/FCM integration). The agent can swap providers, though SuprSend is the default because it unifies iOS and Android with minimal setup.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Deep links in notifications\n\nBoth Emergent platform notifications and your app's push messages support **deep links** - tapping a notification opens a specific screen or resource:\n\n- **Platform notifications** deep-link into the Emergent workspace (for example, directly to a chat thread or published app dashboard).\n- **Your app's notifications** can deep-link to any screen you define. Describe the link structure in chat:\n\n > \"When a user taps the new-message push, open the chat screen with `conversationId` pre-filled.\"\n\nThe agent will configure URL schemes (iOS) and intent filters (Android) automatically.\n\n<Tip>\nDeep links dramatically improve engagement.\n\nUsers who tap a notification convert at 3-5× the rate of users who open the app cold.\n</Tip>\n\n---\n\n## Related topics\n\n<CardGroup cols={2}>\n\n<Card title=\"Emergent Auth\" icon=\"shield-check\" href=\"/emergent-auth-built-in\">\nHow user authentication integrates with device-token registration for push.\n</Card>\n\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\nWhere device tokens and notification state are stored.\n</Card>\n\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nDeep links work smoothly with your custom domain once configured.\n</Card>\n\n<Card title=\"Managing credit usage\" icon=\"credit-card\" href=\"/managing-credit-usage\">\nUnderstand when Emergent sends you low-balance push alerts.\n</Card>\n\n</CardGroup>","published_title":"Push notifications","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"e678d0bb-6e9d-42ad-894c-074ad30323a4","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Build generation for a pre-existing Play Store app","slug":"build-generation-for-a-pre-existing-play-store-app","content":"## Overview\n\nWhen you have an existing app already published on the Google Play Store or Apple App Store, Emergent can generate new builds that preserve your app's identity and signing credentials. This allows you to update your app through Emergent while maintaining continuity with your existing store listing.\n\nTo do this, you'll need to provide Emergent with the signing credentials from your original app. This page walks through extracting the required credential files for both Android and iOS.\n\n<Note>\nIf you're creating a brand new app (not updating an existing store listing), Emergent will generate signing credentials automatically. This guide is only for apps already published to the stores.\n</Note>\n\n## Android signing\n\nIf you built your app on Emergent from the start, signing is fully handled for you: Emergent generates and holds the signing key and uses it for every build. Just click **Publish**, then **Build**, and submit the resulting `.aab` to the Play Console - there is nothing to configure.\n\nThe exception is when you **already have an app listed on the Play Store with the same package name**, signed with its own key. The new AAB won't match the listing's signing key, so the upload fails with a keystore mismatch. To resolve it, contact **support@emergent.sh** - there are two ways, and support will help you pick:\n\n- **Align Emergent to your key**: share your existing `.jks` file and keystore credentials, and Emergent updates the signing setup on our side.\n- **Align Google to Emergent's key**: Emergent provides SHA fingerprints and a `.pem` file that you upload in the Google Play Console as an upload-key reset. The Google side typically takes 2-3 business days to process.\n\n\n<Note title=\"Keep your own keystore safe\">\nIf you manage your own keystore, never commit the keystore file or its passwords to version control. If you lose your keystore, you cannot update your existing Play Store app - you would need to publish as a completely new app.\n</Note>\n## iOS: App Store Connect key\n\nFor iOS apps on the App Store, the App Store Connect API key is auto-created and Emergent-managed after your first TestFlight upload - you do not need to supply one yourself. There is no upload field for push keys in the build settings - if your app uses push notifications, ask the agent to set up **Emergent-managed push notifications** and share your credentials with it before building. If a build fails around push credentials, contact support.\n\n<Info>\nThe App Store Connect API key used to manage provisioning profiles, certificates, and submit builds is auto-created and managed by Emergent after your first TestFlight upload. You do not need to supply an App Store Connect `.p8` key yourself.\n</Info>\n\n\n<Note>\n**Apple login not working during the build?** Sign in with your **Apple Developer account** credentials, not your regular Apple ID.\n</Note>","order":39,"parent_id":null,"icon":"file-text","description":"Build generation for a pre-existing Play Store app","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.236180+00:00","published_at":"2026-09-24T14:08:11.236180+00:00","published_content":"## Overview\n\nWhen you have an existing app already published on the Google Play Store or Apple App Store, Emergent can generate new builds that preserve your app's identity and signing credentials. This allows you to update your app through Emergent while maintaining continuity with your existing store listing.\n\nTo do this, you'll need to provide Emergent with the signing credentials from your original app. This page walks through extracting the required credential files for both Android and iOS.\n\n<Note>\nIf you're creating a brand new app (not updating an existing store listing), Emergent will generate signing credentials automatically. This guide is only for apps already published to the stores.\n</Note>\n\n## Android signing\n\nIf you built your app on Emergent from the start, signing is fully handled for you: Emergent generates and holds the signing key and uses it for every build. Just click **Publish**, then **Build**, and submit the resulting `.aab` to the Play Console - there is nothing to configure.\n\nThe exception is when you **already have an app listed on the Play Store with the same package name**, signed with its own key. The new AAB won't match the listing's signing key, so the upload fails with a keystore mismatch. To resolve it, contact **support@emergent.sh** - there are two ways, and support will help you pick:\n\n- **Align Emergent to your key**: share your existing `.jks` file and keystore credentials, and Emergent updates the signing setup on our side.\n- **Align Google to Emergent's key**: Emergent provides SHA fingerprints and a `.pem` file that you upload in the Google Play Console as an upload-key reset. The Google side typically takes 2-3 business days to process.\n\n\n<Note title=\"Keep your own keystore safe\">\nIf you manage your own keystore, never commit the keystore file or its passwords to version control. If you lose your keystore, you cannot update your existing Play Store app - you would need to publish as a completely new app.\n</Note>\n## iOS: App Store Connect key\n\nFor iOS apps on the App Store, the App Store Connect API key is auto-created and Emergent-managed after your first TestFlight upload - you do not need to supply one yourself. There is no upload field for push keys in the build settings - if your app uses push notifications, ask the agent to set up **Emergent-managed push notifications** and share your credentials with it before building. If a build fails around push credentials, contact support.\n\n<Info>\nThe App Store Connect API key used to manage provisioning profiles, certificates, and submit builds is auto-created and managed by Emergent after your first TestFlight upload. You do not need to supply an App Store Connect `.p8` key yourself.\n</Info>\n\n\n<Note>\n**Apple login not working during the build?** Sign in with your **Apple Developer account** credentials, not your regular Apple ID.\n</Note>","published_title":"Build generation for a pre-existing Play Store app","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"489f0c11-37a5-4b96-83ba-66abce96a8a6","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Troubleshooting","slug":"troubleshooting","content":"## Build Failures\n\nMobile builds on Emergent can fail for a variety of reasons. Most are fixable by reviewing credentials, dependencies, or build logs.\n\n<Info>\nEmergent manages your Expo/EAS account entirely, you never need to create an Expo account, install `eas-cli`, purchase EAS credits, or modify `eas.json`. All native builds (APK/AAB/IPA) are triggered from the **Publish** panel and are built from the **last published code**. If you've made a fix in the agent, re-publish first, then trigger a new build.\n</Info>\n\n**Common causes and fixes:**\n\n- **Expired or missing push credentials**: Emergent manages signing, but push-notification credentials come from you. If your build fails around push credentials, ask the agent to set up **Emergent-managed push notifications** and share your keys with it (the APNs `.p8` push key for iOS, the Firebase service-account key for Android), then re-publish and build again. If it still fails, send the build logs to the agent or contact support.\n- **Pre-existing Play Store app (keystore mismatch)**: if an app with the same package name was already listed on the Play Store, the AAB upload fails because the signing keys don't match. Contact support@emergent.sh - they'll either align Emergent's signing to your existing keystore, or give you the key material (SHA fingerprints and a .pem) to apply in the Play Console as an upload-key reset (2-3 business days on Google's side). See [Publishing to the stores](/publishing-to-the-stores) for details.\n- **Native dependency conflicts**: If your app uses a library that requires specific native modules or has incompatible peer dependencies, the build may fail during dependency resolution. Review the build logs for `npm` or `yarn` errors and ask the agent to update or remove the conflicting package.\n- **Incorrect `app.json` configuration**: Typos in bundle identifiers or version codes will cause validation errors. Bundle IDs are seeded into `app.json` at setup (`com.emergent.<words>.<suffix>`) and are editable in the pre-populated first-build form. Do not modify `eas.json`.\n- **Backend changes not yet published**: Native builds use the last published code. If you have made backend changes since your last publish, **re-publish first**, then trigger the new build from the Publish panel.\n\n<Tip title=\"Read the build logs\">\nAlways expand the full build log in the Emergent Publish panel. The error is usually near the end and tells you exactly which step failed.\n</Tip>\n\n---\n\n## Submission Rejected\n\nApple and Google both review submissions before your app goes live. Common rejection reasons include:\n\n| Reason | Platform | Fix |\n|--------|----------|-----|\n| Missing privacy policy or terms of service | Both | Add a publicly accessible link in your app's store listing and in-app settings. |\n| Sign in with Apple not implemented | iOS | If you offer any third-party sign-in (Google, Facebook), Apple requires you also offer Sign in with Apple. Add it or remove other social logins. |\n| App crashes on launch | Both | Test on a physical device before submission. Production builds may behave differently from preview, always test a production `.ipa` or `.aab`. |\n| Incomplete or misleading screenshots | Both | Use real app screenshots that accurately represent functionality. Avoid mockups or marketing graphics that don't match the actual UI. |\n| Incorrect age rating | Both | Ensure your app's content rating matches what reviewers see. If your app allows user-generated content, declare it and implement moderation. |\n| Bundle ID or package name mismatch | Both | The identifier in your build must exactly match what you registered in App Store Connect or Google Play Console. Check `app.json` → `ios.bundleIdentifier` and `android.package`. |\n\n<Warning title=\"Sign in with Apple audience validation\">\nA common iOS rejection occurs when Sign in with Apple is configured with the wrong audience (client ID). See the dedicated section below for the fix, this is a backend-only configuration change and does not require a new build number or resubmission.\n</Warning>\n\nIf your app is rejected, the store will provide specific feedback. Address each point and work with the Emergent agent to resolve the underlying issue.\n\n---\n\n## Updates Not Appearing\n\nYou've made a change but users aren't seeing the new version.\n\n**Why this happens and what to do:**\n\n- **OTA updates are not enabled**: Emergent does not currently deliver over-the-air updates. Getting changes to your users always means re-publishing and then building.\n- **Backend-only changes**: changes to your backend (API logic, database) ship when you **re-publish** - no new build or store submission is needed, because the backend runs on Emergent's servers.\n- **App changes (JS or native)**: any change to the app itself - JavaScript included - requires a re-publish followed by a **new native build** from the Publish panel, and a store submission for that new build.\n\n<Steps>\n<Step title=\"Re-publish your latest changes\">\nIn the Emergent platform, use the **Re-publish** button to publish your latest code. Native builds always use the last published version: fix first, re-publish, then rebuild.\n</Step>\n<Step title=\"Trigger a new native build\">\nStart a new build from the Publish panel for the target platform. OTA updates are not enabled, so a new build is required for any app change.\n</Step>\n<Step title=\"Submit the new build to the stores\">\nFor Android, upload the new `.aab` to the Play Console. For iOS, the TestFlight upload is handled for you; promote the build in App Store Connect.\n</Step>\n</Steps>\n\n## Icons Show as Boxes on Android\n\n<Note>\nThis issue affects only **older Emergent-generated apps**. The app template has since been fixed, so newly created projects should not encounter it.\n</Note>\n\nWhen testing on Android, vector icons from libraries like `@expo/vector-icons` or `react-native-vector-icons` may render as empty boxes (sometimes called \"tofu\") in certain builds.\n\n**Cause:** The older app template did not bundle every icon font correctly for Android. The iOS build was unaffected, which is why the issue is Android-specific.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Use a production build for testing\">\nTrigger a new native build from the Emergent Publish panel. Standalone builds include all icon fonts your app declares.\n</Step>\n<Step title=\"Migrate to SVG assets (recommended long-term fix)\">\nFor a durable solution, ask the agent to replace vector icon libraries with SVG assets rendered via `react-native-svg`. SVG migration is the recommended long-term approach, as it avoids font-bundling issues entirely and scales well across screen densities.\n</Step>\n<Step title=\"Re-publish before rebuilding\">\nRemember: native builds use the last published code. After the agent makes icon changes, use **Re-publish** to publish, then trigger a new build from the Publish panel.\n</Step>\n</Steps>\n\n<Tip>\nOnce you have a properly built standalone `.apk` or `.aab` from the updated template, icons will render correctly.\n</Tip>\n\n---\n\n## Sign in with Apple Rejection\n\n**Symptom:** Your iOS app is rejected with a message like \"Sign in with Apple does not work\" or \"Invalid client configuration,\" even though authentication works fine in testing.\n\n**Root cause:** Sign in with Apple validates the **audience (`aud`) claim** in the ID token. If your backend or auth provider is configured to use the wrong client ID, often the **Services ID** instead of the **bundle identifier**, Apple's review team will see a validation error.\n\n**Important:** This is a **backend-only configuration fix**. It applies to the build already in review. Bumping the build number and submitting a new binary does not resolve this issue and is not necessary.\n\n**How to fix:**\n\n<Steps>\n<Step title=\"Identify which identifier you're using\">\nCheck your backend's Apple auth configuration or your Firebase/Auth0/Supabase settings. Look for the field labeled \"Client ID,\" \"Services ID,\" or \"Audience.\"\n</Step>\n<Step title=\"Use the bundle ID, not the Services ID\">\nFor native iOS apps, the `aud` claim in the ID token must match your app's **bundle identifier** (e.g., `com.emergent.yourapp.xyz`), **not** the Services ID you created in the Apple Developer portal.\n</Step>\n<Step title=\"Ask the agent to update your backend auth config\">\nDescribe the misconfiguration to the Emergent agent. The fix is made in the backend code/configuration, for example, updating the audience field in your Firebase, Auth0, Supabase, or custom backend Apple connection settings.\n</Step>\n<Step title=\"Re-publish the backend fix\">\nUse **Re-publish** to publish the corrected backend configuration. Because this is a backend-only change, the fix takes effect without a new native build or store resubmission, Apple can re-review the same binary once your backend is corrected.\n</Step>\n</Steps>\n\n<Warning>\nDo not share the same Services ID across web and native. Use the bundle ID for iOS native apps and a separate Services ID for your web client if you have a browser-based flow.\n</Warning>\n\n---\n\n## Quick Reference\n\nAn at-a-glance checklist for mobile publishing and troubleshooting.\n\n### Pre-Submission Checklist\n\n- [ ] Bundle ID (iOS) and package name (Android) match your store registrations\n- [ ] App version and build number - handled automatically by Emergent, nothing to set\n- [ ] App icon and splash screen assets present and correctly sized\n- [ ] Privacy policy and terms of service URLs live and accessible\n- [ ] Sign in with Apple implemented if you offer any third-party sign-in (iOS only)\n- [ ] All required permissions declared and justified in store listing\n- [ ] Latest changes re-published before triggering a native build\n- [ ] Push credentials shared with the agent, if your app uses push notifications (ask the agent to set up Emergent-managed push before you build)\n- [ ] App tested on a production build - via TestFlight (iOS) or by downloading the APK (Android)\n\n### Emergent Mobile Build Workflow\n\n| Task | How to do it on Emergent |\n|------|--------------------------|\n| Trigger a native iOS or Android build | Publish panel → select platform |\n| Ship a backend-only update | **Re-publish** in the Publish panel |\n| Ship an app update (JS or native) | **Re-publish**, then trigger a new build from the Publish panel |\n| Submit to App Store | Emergent handles TestFlight upload; App Store Connect API key is auto-managed |\n| Submit to Play Store | Emergent handles AAB submission; register your package name in Play Console |\n| View build logs | Publish panel → build history |\n| Contact support | support@emergent.sh or in-app live chat (Emmy) |\n\n<Note>\nYou do not run `eas build`, `eas submit`, `eas update`, `eas credentials`, or any `eas-cli` commands. All of these are handled by Emergent. Do not modify `eas.json`.\n</Note>\n\n### Troubleshooting Decision Tree\n\n```\nBuild failed?\n├─ Check build logs in the Publish panel\n├─ Send the build logs to the agent - it can check push-credential and other configuration issues\n├─ Ensure latest code is redeployed (Re-publish) before rebuilding\n└─ Contact support@emergent.sh for keystore/credential issues\n\nSubmission rejected?\n├─ Review rejection notice from Apple/Google\n├─ Fix each listed issue (ask the agent for backend/code fixes)\n├─ Re-publish after backend fixes\n└─ Trigger a new native build only if native code changed\n\nUpdate not appearing?\n├─ Re-publish your latest changes first\n├─ Trigger a new native build from the Publish panel (OTA updates are not enabled)\n└─ Submit the new build to the stores\n\nIcons render as boxes (Android)?\n├─ Trigger a new build from the updated template\n└─ Ask the agent to migrate to SVG assets (recommended long-term fix)\n\nSign in with Apple fails in review?\n├─ Fix audience/bundle-ID mismatch in your backend config (backend-only fix)\n├─ Re-publish the backend fix\n└─ No new build number or binary needed, Apple re-reviews the same build\n```\n\n<Info>\nFor deeper context on how builds and published versions work, see [Publishing to the stores](/publishing-to-the-stores). For performance and stability issues, see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting).\n</Info>","order":40,"parent_id":null,"icon":"file-text","description":"Troubleshooting","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.258484+00:00","published_at":"2026-09-24T14:08:11.258484+00:00","published_content":"## Build Failures\n\nMobile builds on Emergent can fail for a variety of reasons. Most are fixable by reviewing credentials, dependencies, or build logs.\n\n<Info>\nEmergent manages your Expo/EAS account entirely, you never need to create an Expo account, install `eas-cli`, purchase EAS credits, or modify `eas.json`. All native builds (APK/AAB/IPA) are triggered from the **Publish** panel and are built from the **last published code**. If you've made a fix in the agent, re-publish first, then trigger a new build.\n</Info>\n\n**Common causes and fixes:**\n\n- **Expired or missing push credentials**: Emergent manages signing, but push-notification credentials come from you. If your build fails around push credentials, ask the agent to set up **Emergent-managed push notifications** and share your keys with it (the APNs `.p8` push key for iOS, the Firebase service-account key for Android), then re-publish and build again. If it still fails, send the build logs to the agent or contact support.\n- **Pre-existing Play Store app (keystore mismatch)**: if an app with the same package name was already listed on the Play Store, the AAB upload fails because the signing keys don't match. Contact support@emergent.sh - they'll either align Emergent's signing to your existing keystore, or give you the key material (SHA fingerprints and a .pem) to apply in the Play Console as an upload-key reset (2-3 business days on Google's side). See [Publishing to the stores](/publishing-to-the-stores) for details.\n- **Native dependency conflicts**: If your app uses a library that requires specific native modules or has incompatible peer dependencies, the build may fail during dependency resolution. Review the build logs for `npm` or `yarn` errors and ask the agent to update or remove the conflicting package.\n- **Incorrect `app.json` configuration**: Typos in bundle identifiers or version codes will cause validation errors. Bundle IDs are seeded into `app.json` at setup (`com.emergent.<words>.<suffix>`) and are editable in the pre-populated first-build form. Do not modify `eas.json`.\n- **Backend changes not yet published**: Native builds use the last published code. If you have made backend changes since your last publish, **re-publish first**, then trigger the new build from the Publish panel.\n\n<Tip title=\"Read the build logs\">\nAlways expand the full build log in the Emergent Publish panel. The error is usually near the end and tells you exactly which step failed.\n</Tip>\n\n---\n\n## Submission Rejected\n\nApple and Google both review submissions before your app goes live. Common rejection reasons include:\n\n| Reason | Platform | Fix |\n|--------|----------|-----|\n| Missing privacy policy or terms of service | Both | Add a publicly accessible link in your app's store listing and in-app settings. |\n| Sign in with Apple not implemented | iOS | If you offer any third-party sign-in (Google, Facebook), Apple requires you also offer Sign in with Apple. Add it or remove other social logins. |\n| App crashes on launch | Both | Test on a physical device before submission. Production builds may behave differently from preview, always test a production `.ipa` or `.aab`. |\n| Incomplete or misleading screenshots | Both | Use real app screenshots that accurately represent functionality. Avoid mockups or marketing graphics that don't match the actual UI. |\n| Incorrect age rating | Both | Ensure your app's content rating matches what reviewers see. If your app allows user-generated content, declare it and implement moderation. |\n| Bundle ID or package name mismatch | Both | The identifier in your build must exactly match what you registered in App Store Connect or Google Play Console. Check `app.json` → `ios.bundleIdentifier` and `android.package`. |\n\n<Warning title=\"Sign in with Apple audience validation\">\nA common iOS rejection occurs when Sign in with Apple is configured with the wrong audience (client ID). See the dedicated section below for the fix, this is a backend-only configuration change and does not require a new build number or resubmission.\n</Warning>\n\nIf your app is rejected, the store will provide specific feedback. Address each point and work with the Emergent agent to resolve the underlying issue.\n\n---\n\n## Updates Not Appearing\n\nYou've made a change but users aren't seeing the new version.\n\n**Why this happens and what to do:**\n\n- **OTA updates are not enabled**: Emergent does not currently deliver over-the-air updates. Getting changes to your users always means re-publishing and then building.\n- **Backend-only changes**: changes to your backend (API logic, database) ship when you **re-publish** - no new build or store submission is needed, because the backend runs on Emergent's servers.\n- **App changes (JS or native)**: any change to the app itself - JavaScript included - requires a re-publish followed by a **new native build** from the Publish panel, and a store submission for that new build.\n\n<Steps>\n<Step title=\"Re-publish your latest changes\">\nIn the Emergent platform, use the **Re-publish** button to publish your latest code. Native builds always use the last published version: fix first, re-publish, then rebuild.\n</Step>\n<Step title=\"Trigger a new native build\">\nStart a new build from the Publish panel for the target platform. OTA updates are not enabled, so a new build is required for any app change.\n</Step>\n<Step title=\"Submit the new build to the stores\">\nFor Android, upload the new `.aab` to the Play Console. For iOS, the TestFlight upload is handled for you; promote the build in App Store Connect.\n</Step>\n</Steps>\n\n## Icons Show as Boxes on Android\n\n<Note>\nThis issue affects only **older Emergent-generated apps**. The app template has since been fixed, so newly created projects should not encounter it.\n</Note>\n\nWhen testing on Android, vector icons from libraries like `@expo/vector-icons` or `react-native-vector-icons` may render as empty boxes (sometimes called \"tofu\") in certain builds.\n\n**Cause:** The older app template did not bundle every icon font correctly for Android. The iOS build was unaffected, which is why the issue is Android-specific.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Use a production build for testing\">\nTrigger a new native build from the Emergent Publish panel. Standalone builds include all icon fonts your app declares.\n</Step>\n<Step title=\"Migrate to SVG assets (recommended long-term fix)\">\nFor a durable solution, ask the agent to replace vector icon libraries with SVG assets rendered via `react-native-svg`. SVG migration is the recommended long-term approach, as it avoids font-bundling issues entirely and scales well across screen densities.\n</Step>\n<Step title=\"Re-publish before rebuilding\">\nRemember: native builds use the last published code. After the agent makes icon changes, use **Re-publish** to publish, then trigger a new build from the Publish panel.\n</Step>\n</Steps>\n\n<Tip>\nOnce you have a properly built standalone `.apk` or `.aab` from the updated template, icons will render correctly.\n</Tip>\n\n---\n\n## Sign in with Apple Rejection\n\n**Symptom:** Your iOS app is rejected with a message like \"Sign in with Apple does not work\" or \"Invalid client configuration,\" even though authentication works fine in testing.\n\n**Root cause:** Sign in with Apple validates the **audience (`aud`) claim** in the ID token. If your backend or auth provider is configured to use the wrong client ID, often the **Services ID** instead of the **bundle identifier**, Apple's review team will see a validation error.\n\n**Important:** This is a **backend-only configuration fix**. It applies to the build already in review. Bumping the build number and submitting a new binary does not resolve this issue and is not necessary.\n\n**How to fix:**\n\n<Steps>\n<Step title=\"Identify which identifier you're using\">\nCheck your backend's Apple auth configuration or your Firebase/Auth0/Supabase settings. Look for the field labeled \"Client ID,\" \"Services ID,\" or \"Audience.\"\n</Step>\n<Step title=\"Use the bundle ID, not the Services ID\">\nFor native iOS apps, the `aud` claim in the ID token must match your app's **bundle identifier** (e.g., `com.emergent.yourapp.xyz`), **not** the Services ID you created in the Apple Developer portal.\n</Step>\n<Step title=\"Ask the agent to update your backend auth config\">\nDescribe the misconfiguration to the Emergent agent. The fix is made in the backend code/configuration, for example, updating the audience field in your Firebase, Auth0, Supabase, or custom backend Apple connection settings.\n</Step>\n<Step title=\"Re-publish the backend fix\">\nUse **Re-publish** to publish the corrected backend configuration. Because this is a backend-only change, the fix takes effect without a new native build or store resubmission, Apple can re-review the same binary once your backend is corrected.\n</Step>\n</Steps>\n\n<Warning>\nDo not share the same Services ID across web and native. Use the bundle ID for iOS native apps and a separate Services ID for your web client if you have a browser-based flow.\n</Warning>\n\n---\n\n## Quick Reference\n\nAn at-a-glance checklist for mobile publishing and troubleshooting.\n\n### Pre-Submission Checklist\n\n- [ ] Bundle ID (iOS) and package name (Android) match your store registrations\n- [ ] App version and build number - handled automatically by Emergent, nothing to set\n- [ ] App icon and splash screen assets present and correctly sized\n- [ ] Privacy policy and terms of service URLs live and accessible\n- [ ] Sign in with Apple implemented if you offer any third-party sign-in (iOS only)\n- [ ] All required permissions declared and justified in store listing\n- [ ] Latest changes re-published before triggering a native build\n- [ ] Push credentials shared with the agent, if your app uses push notifications (ask the agent to set up Emergent-managed push before you build)\n- [ ] App tested on a production build - via TestFlight (iOS) or by downloading the APK (Android)\n\n### Emergent Mobile Build Workflow\n\n| Task | How to do it on Emergent |\n|------|--------------------------|\n| Trigger a native iOS or Android build | Publish panel → select platform |\n| Ship a backend-only update | **Re-publish** in the Publish panel |\n| Ship an app update (JS or native) | **Re-publish**, then trigger a new build from the Publish panel |\n| Submit to App Store | Emergent handles TestFlight upload; App Store Connect API key is auto-managed |\n| Submit to Play Store | Emergent handles AAB submission; register your package name in Play Console |\n| View build logs | Publish panel → build history |\n| Contact support | support@emergent.sh or in-app live chat (Emmy) |\n\n<Note>\nYou do not run `eas build`, `eas submit`, `eas update`, `eas credentials`, or any `eas-cli` commands. All of these are handled by Emergent. Do not modify `eas.json`.\n</Note>\n\n### Troubleshooting Decision Tree\n\n```\nBuild failed?\n├─ Check build logs in the Publish panel\n├─ Send the build logs to the agent - it can check push-credential and other configuration issues\n├─ Ensure latest code is redeployed (Re-publish) before rebuilding\n└─ Contact support@emergent.sh for keystore/credential issues\n\nSubmission rejected?\n├─ Review rejection notice from Apple/Google\n├─ Fix each listed issue (ask the agent for backend/code fixes)\n├─ Re-publish after backend fixes\n└─ Trigger a new native build only if native code changed\n\nUpdate not appearing?\n├─ Re-publish your latest changes first\n├─ Trigger a new native build from the Publish panel (OTA updates are not enabled)\n└─ Submit the new build to the stores\n\nIcons render as boxes (Android)?\n├─ Trigger a new build from the updated template\n└─ Ask the agent to migrate to SVG assets (recommended long-term fix)\n\nSign in with Apple fails in review?\n├─ Fix audience/bundle-ID mismatch in your backend config (backend-only fix)\n├─ Re-publish the backend fix\n└─ No new build number or binary needed, Apple re-reviews the same build\n```\n\n<Info>\nFor deeper context on how builds and published versions work, see [Publishing to the stores](/publishing-to-the-stores). For performance and stability issues, see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting).\n</Info>","published_title":"Troubleshooting","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"72306f9a-240a-45e7-8764-d5b7f30e0b93","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Best Practices","slug":"best-practices","content":"## Overview\n\nFollowing mobile best practices ensures your app delivers a smooth user experience, passes store review, and handles system permissions correctly. This guide covers the essential patterns for Expo-based mobile apps built on Emergent.\n\n<Tip>\nFor better results, start with a strong prompt. See [Write prompts that work](/write-prompts-that-work) for prompting patterns that lead to higher-quality mobile builds.\n</Tip>\n\n## Device Permission Best Practices\n\nModern mobile apps must request runtime permissions for sensitive features like the camera, location, or contacts. Expo provides a consistent cross-platform API, but the user experience and system behavior differ between iOS and Android.\n\n### Request Permissions Contextually\n\nAlways ask for a permission immediately before you need it, not on app launch. Users are far more likely to grant access when they understand why your app needs it.\n\n<Tip title=\"Show value first\">\nDisplay a screen or modal explaining what the feature does before calling `requestPermissionsAsync`. For example, show a \"Scan a barcode to add items\" prompt before requesting camera access.\n</Tip>\n\n### The Four Permission States\n\nExpo permission hooks return one of four states:\n\n| State | Description | Action |\n|-------|-------------|--------|\n| `undetermined` | User has not been asked yet | Call `requestPermissionsAsync` |\n| `granted` | Permission allowed | Proceed with feature |\n| `denied` | User declined, but **can** be asked again | Show rationale, then re-request |\n| `denied` + `canAskAgain=false` | User declined and selected \"Don't ask again\" (Android) or denied twice (iOS) | Deep-link to Settings |\n\nThe `canAskAgain` boolean tells you whether calling `requestPermissionsAsync` will show the system dialog or silently return `denied`.\n\n```typescript\nimport * as Camera from 'expo-camera';\n\nconst { status, canAskAgain } = await Camera.getCameraPermissionsAsync();\n\nif (status === 'granted') {\n // proceed\n} else if (canAskAgain) {\n const { status: newStatus } = await Camera.requestCameraPermissionsAsync();\n if (newStatus === 'granted') {\n // proceed\n }\n} else {\n // blocked - guide user to Settings\n}\n```\n\n### Deep-Link to Settings When Blocked\n\nWhen `canAskAgain` is `false`, the only way forward is for the user to manually enable the permission in system Settings. Use `expo-linking` to open the app's settings page:\n\n```typescript\nimport * as Linking from 'expo-linking';\n\nif (!canAskAgain) {\n Alert.alert(\n 'Camera Access Required',\n 'Please enable camera access in Settings to use this feature.',\n [\n { text: 'Cancel', style: 'cancel' },\n { text: 'Open Settings', onPress: () => Linking.openSettings() }\n ]\n );\n}\n```\n\n<Warning title=\"Test the blocked state\">\nDuring development, intentionally deny permissions multiple times to verify your Settings deep-link flow works on both platforms.\n</Warning>\n\n### iOS Usage Description Strings\n\nApple requires a human-readable explanation for every permission your app requests. These strings appear in the system permission dialog and are mandatory for App Store review.\n\nAdd them to the `ios` section of your `app.json`:\n\n```json\n{\n \"expo\": {\n \"ios\": {\n \"infoPlist\": {\n \"NSCameraUsageDescription\": \"This app uses the camera to scan barcodes and take photos of receipts.\",\n \"NSPhotoLibraryUsageDescription\": \"This app accesses your photo library to let you upload images.\",\n \"NSLocationWhenInUseUsageDescription\": \"This app uses your location to show nearby stores.\"\n }\n }\n }\n}\n```\n\nEach `NS*UsageDescription` key corresponds to a specific permission. Common keys include:\n\n- `NSCameraUsageDescription` - Camera\n- `NSPhotoLibraryUsageDescription` - Photo library read\n- `NSPhotoLibraryAddUsageDescription` - Photo library write (iOS 11+)\n- `NSMicrophoneUsageDescription` - Microphone\n- `NSLocationWhenInUseUsageDescription` - Location while app is open\n- `NSLocationAlwaysUsageDescription` - Background location\n- `NSContactsUsageDescription` - Contacts\n- `NSCalendarsUsageDescription` - Calendar\n- `NSRemindersUsageDescription` - Reminders\n- `NSMotionUsageDescription` - Motion & fitness sensors\n- `NSFaceIDUsageDescription` - Face ID\n\n<Note title=\"Emergent regenerates the native project\">\nWhen you update `app.json` and rebuild, Emergent agents automatically merge your usage descriptions into the iOS Info.plist. No manual Xcode changes are needed.\n</Note>\n\nWrite clear, specific descriptions that explain the user benefit - not just the technical capability. Apple rejects vague strings like \"This app needs camera access.\"\n\n### Android Permissions in app.json\n\nAndroid permissions are declared in the `android.permissions` array. Expo auto-includes common permissions based on the libraries you import, but you can add extras if needed:\n\n```json\n{\n \"expo\": {\n \"android\": {\n \"permissions\": [\n \"CAMERA\",\n \"ACCESS_FINE_LOCATION\"\n ]\n }\n }\n}\n```\n\nUnlike iOS, Android does not require usage descriptions in the manifest (though showing your own rationale UI is still recommended).\n\n## Related Resources\n\n<CardGroup cols={2}>\n <Card title=\"Publishing to the Stores\" icon=\"store\" href=\"/publishing-to-the-stores\">\n Submit your app to the App Store and Play Store\n </Card>\n <Card title=\"The Chat-to-Published app Flow\" icon=\"messages-square\" href=\"/the-chat-to-published app-flow\">\n How Emergent agents build and test your app\n </Card>\n</CardGroup>","order":41,"parent_id":null,"icon":"list-checks","description":"Best practices for building, testing, and publishing mobile apps on Emergent.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:11.242370+00:00","published_at":"2026-09-24T14:08:11.242370+00:00","published_content":"## Overview\n\nFollowing mobile best practices ensures your app delivers a smooth user experience, passes store review, and handles system permissions correctly. This guide covers the essential patterns for Expo-based mobile apps built on Emergent.\n\n<Tip>\nFor better results, start with a strong prompt. See [Write prompts that work](/write-prompts-that-work) for prompting patterns that lead to higher-quality mobile builds.\n</Tip>\n\n## Device Permission Best Practices\n\nModern mobile apps must request runtime permissions for sensitive features like the camera, location, or contacts. Expo provides a consistent cross-platform API, but the user experience and system behavior differ between iOS and Android.\n\n### Request Permissions Contextually\n\nAlways ask for a permission immediately before you need it, not on app launch. Users are far more likely to grant access when they understand why your app needs it.\n\n<Tip title=\"Show value first\">\nDisplay a screen or modal explaining what the feature does before calling `requestPermissionsAsync`. For example, show a \"Scan a barcode to add items\" prompt before requesting camera access.\n</Tip>\n\n### The Four Permission States\n\nExpo permission hooks return one of four states:\n\n| State | Description | Action |\n|-------|-------------|--------|\n| `undetermined` | User has not been asked yet | Call `requestPermissionsAsync` |\n| `granted` | Permission allowed | Proceed with feature |\n| `denied` | User declined, but **can** be asked again | Show rationale, then re-request |\n| `denied` + `canAskAgain=false` | User declined and selected \"Don't ask again\" (Android) or denied twice (iOS) | Deep-link to Settings |\n\nThe `canAskAgain` boolean tells you whether calling `requestPermissionsAsync` will show the system dialog or silently return `denied`.\n\n```typescript\nimport * as Camera from 'expo-camera';\n\nconst { status, canAskAgain } = await Camera.getCameraPermissionsAsync();\n\nif (status === 'granted') {\n // proceed\n} else if (canAskAgain) {\n const { status: newStatus } = await Camera.requestCameraPermissionsAsync();\n if (newStatus === 'granted') {\n // proceed\n }\n} else {\n // blocked - guide user to Settings\n}\n```\n\n### Deep-Link to Settings When Blocked\n\nWhen `canAskAgain` is `false`, the only way forward is for the user to manually enable the permission in system Settings. Use `expo-linking` to open the app's settings page:\n\n```typescript\nimport * as Linking from 'expo-linking';\n\nif (!canAskAgain) {\n Alert.alert(\n 'Camera Access Required',\n 'Please enable camera access in Settings to use this feature.',\n [\n { text: 'Cancel', style: 'cancel' },\n { text: 'Open Settings', onPress: () => Linking.openSettings() }\n ]\n );\n}\n```\n\n<Warning title=\"Test the blocked state\">\nDuring development, intentionally deny permissions multiple times to verify your Settings deep-link flow works on both platforms.\n</Warning>\n\n### iOS Usage Description Strings\n\nApple requires a human-readable explanation for every permission your app requests. These strings appear in the system permission dialog and are mandatory for App Store review.\n\nAdd them to the `ios` section of your `app.json`:\n\n```json\n{\n \"expo\": {\n \"ios\": {\n \"infoPlist\": {\n \"NSCameraUsageDescription\": \"This app uses the camera to scan barcodes and take photos of receipts.\",\n \"NSPhotoLibraryUsageDescription\": \"This app accesses your photo library to let you upload images.\",\n \"NSLocationWhenInUseUsageDescription\": \"This app uses your location to show nearby stores.\"\n }\n }\n }\n}\n```\n\nEach `NS*UsageDescription` key corresponds to a specific permission. Common keys include:\n\n- `NSCameraUsageDescription` - Camera\n- `NSPhotoLibraryUsageDescription` - Photo library read\n- `NSPhotoLibraryAddUsageDescription` - Photo library write (iOS 11+)\n- `NSMicrophoneUsageDescription` - Microphone\n- `NSLocationWhenInUseUsageDescription` - Location while app is open\n- `NSLocationAlwaysUsageDescription` - Background location\n- `NSContactsUsageDescription` - Contacts\n- `NSCalendarsUsageDescription` - Calendar\n- `NSRemindersUsageDescription` - Reminders\n- `NSMotionUsageDescription` - Motion & fitness sensors\n- `NSFaceIDUsageDescription` - Face ID\n\n<Note title=\"Emergent regenerates the native project\">\nWhen you update `app.json` and rebuild, Emergent agents automatically merge your usage descriptions into the iOS Info.plist. No manual Xcode changes are needed.\n</Note>\n\nWrite clear, specific descriptions that explain the user benefit - not just the technical capability. Apple rejects vague strings like \"This app needs camera access.\"\n\n### Android Permissions in app.json\n\nAndroid permissions are declared in the `android.permissions` array. Expo auto-includes common permissions based on the libraries you import, but you can add extras if needed:\n\n```json\n{\n \"expo\": {\n \"android\": {\n \"permissions\": [\n \"CAMERA\",\n \"ACCESS_FINE_LOCATION\"\n ]\n }\n }\n}\n```\n\nUnlike iOS, Android does not require usage descriptions in the manifest (though showing your own rationale UI is still recommended).\n\n## Related Resources\n\n<CardGroup cols={2}>\n <Card title=\"Publishing to the Stores\" icon=\"store\" href=\"/publishing-to-the-stores\">\n Submit your app to the App Store and Play Store\n </Card>\n <Card title=\"The Chat-to-Published app Flow\" icon=\"messages-square\" href=\"/the-chat-to-published app-flow\">\n How Emergent agents build and test your app\n </Card>\n</CardGroup>","published_title":"Best Practices","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"df155d34-0658-4a2b-a5d4-5b01388fa3c7","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Plans & the free tier","slug":"plans-the-free-tier","content":"## Overview\n\nEmergent offers a tiered pricing model designed to match your development needs and budget. Whether you're exploring the platform for the first time, building personal projects, or scaling production applications, there's a plan that fits.\n\nEvery plan is **credit-based**: building, testing, and publishing your apps consumes credits. The main difference between plans is your monthly credit allocation, published app capability, and access to advanced features.\n\n## Plan comparison\n\n<Callout type=\"info\" title=\"Credit-based usage\">\nAll plans use credits to power AI agents that write, test, and publish your code. Higher tiers give you more credits per month and unlock additional capabilities.\n</Callout>\n\n| Feature | Free | Standard | Pro |\n|---------|------|----------|-----|\n| **Monthly credits** | 10 credits on your first day | Higher allocation | Highest allocation |\n| **Publish to production** | ❌ | ✅ | ✅ |\n| **Custom domains** | ❌ | ✅ | ✅ |\n| **Advanced features** | Limited | Full access | Full access + priority |\n| **Support** | Community | Standard | Priority |\n| **Best for** | Exploration & learning | Personal projects & prototypes | Production apps & teams |\n\n<Note>\nMonthly subscription credits **do not roll over**, unused subscription credits expire at the end of each billing cycle. However, purchased top-up credits never expire.\n</Note>\n\n## Free tier\n\nThe Free tier gives you **10 credits on your first day** to explore Emergent and understand how vibe-coding works. You can:\n\n- Chat with AI agents to build and iterate on apps\n- Test features and workflows in the workspace\n- Learn the platform's capabilities hands-on\n\n**What you cannot do:**\n\n- Publish apps to production (published app is credit-gated, requiring a minimum of 50 credits to start; free-tier users may qualify for a free frontend-only published app)\n- Use [custom domains](/custom-domain)\n- Access priority support or advanced agent customization\n\nThe Free tier is perfect for evaluating Emergent, experimenting with ideas, or learning how agentic development works before committing to a paid plan.\n\n<Tip>\nIf you run out of free credits, you can upgrade to Standard or Pro immediately - your new credit allocation becomes available right away.\n</Tip>\n\n## Standard plan\n\nThe Standard plan is designed for developers building personal projects, side projects, and production-ready prototypes. You get:\n\n- A larger monthly credit allocation\n- Full published app capability (your apps go live at `yourapp.emergent.host`)\n- Support for [custom domains](/custom-domain)\n- Access to all core platform features\n\nStandard is the right choice when you're ready to ship real applications, need your work publicly accessible, or want consistent monthly credits for ongoing development.\n\n## Pro plan\n\nThe Pro plan is built for **teams, businesses, and power users** who need maximum capacity and priority treatment. It includes:\n\n- The highest monthly credit allocation\n- Priority support with faster response times\n- Early access to new features and capabilities\n- All Standard features, plus advanced configurations\n\nChoose Pro when you're scaling production apps, running a development team, or need guaranteed availability and support.\n\n<Info>\nBoth Standard and Pro support [custom agents](/custom-agents) and [AI media generation](/ai-media-generation-image-video-audio). Credit usage varies by job complexity - see [What is a Job?](/what-is-a-job) for details.\n</Info>\n\n## Choosing the right plan\n\n<Steps>\n<Step title=\"Evaluate your published app needs\">\nIf you need to publish apps to production, you must choose Standard or Pro. Free tier is workspace-only.\n</Step>\n\n<Step title=\"Estimate your monthly credit usage\">\nConsider how many apps you'll build, how frequently you'll iterate, and whether you need [Wingman](/what-is-wingman) assistance. Larger, more complex jobs consume more credits.\n</Step>\n\n<Step title=\"Factor in team size and support requirements\">\nSolo developers typically do well on Standard. Teams, agencies, or businesses benefit from Pro's priority support and higher limits.\n</Step>\n</Steps>\n\n## Bulk credits & custom pricing\n\n<Callout type=\"tip\" title=\"Need more credits?\">\nIf your usage exceeds your plan's monthly allocation, you can **purchase bulk credits** with custom pricing tailored to your volume. This option is available to Standard and Pro customers - contact sales to discuss your needs.\n</Callout>\n\nBulk credit purchases are one-time add-ons that supplement your monthly plan. They're ideal for:\n\n- Seasonal spikes in development activity\n- Large migration or refactoring projects\n- Agencies managing multiple client apps\n\n\n## Credit management\n\nAll plans follow the same credit lifecycle rules:\n\n- Credits recharge monthly on your billing date\n- Unused **subscription** credits **do not roll over**, they expire at cycle end; purchased top-up credits never expire\n- You can monitor usage in real-time from your workspace dashboard\n\nFor details on expiry, top-ups, and recharge timing, see [Managing credit usage](/managing-credit-usage).\n\n<Warning>\nPublishing, testing, and generating media with AI agents all consume credits. Plan your monthly allocation carefully, especially if you're building multiple apps or iterating frequently.\n</Warning>","order":43,"parent_id":null,"icon":"file-text","description":"Plans & the free tier","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-10-05T14:08:56.845338+00:00","published_at":"2026-10-05T14:08:56.845338+00:00","published_content":"## Overview\n\nEmergent offers a tiered pricing model designed to match your development needs and budget. Whether you're exploring the platform for the first time, building personal projects, or scaling production applications, there's a plan that fits.\n\nEvery plan is **credit-based**: building, testing, and publishing your apps consumes credits. The main difference between plans is your monthly credit allocation, published app capability, and access to advanced features.\n\n## Plan comparison\n\n<Callout type=\"info\" title=\"Credit-based usage\">\nAll plans use credits to power AI agents that write, test, and publish your code. Higher tiers give you more credits per month and unlock additional capabilities.\n</Callout>\n\n| Feature | Free | Standard | Pro |\n|---------|------|----------|-----|\n| **Monthly credits** | 10 credits on your first day | Higher allocation | Highest allocation |\n| **Publish to production** | ❌ | ✅ | ✅ |\n| **Custom domains** | ❌ | ✅ | ✅ |\n| **Advanced features** | Limited | Full access | Full access + priority |\n| **Support** | Community | Standard | Priority |\n| **Best for** | Exploration & learning | Personal projects & prototypes | Production apps & teams |\n\n<Note>\nMonthly subscription credits **do not roll over**, unused subscription credits expire at the end of each billing cycle. However, purchased top-up credits never expire.\n</Note>\n\n## Free tier\n\nThe Free tier gives you **10 credits on your first day** to explore Emergent and understand how vibe-coding works. You can:\n\n- Chat with AI agents to build and iterate on apps\n- Test features and workflows in the workspace\n- Learn the platform's capabilities hands-on\n\n**What you cannot do:**\n\n- Publish apps to production (published app is credit-gated, requiring a minimum of 50 credits to start; free-tier users may qualify for a free frontend-only published app)\n- Use [custom domains](/custom-domain)\n- Access priority support or advanced agent customization\n\nThe Free tier is perfect for evaluating Emergent, experimenting with ideas, or learning how agentic development works before committing to a paid plan.\n\n<Tip>\nIf you run out of free credits, you can upgrade to Standard or Pro immediately - your new credit allocation becomes available right away.\n</Tip>\n\n## Standard plan\n\nThe Standard plan is designed for developers building personal projects, side projects, and production-ready prototypes. You get:\n\n- A larger monthly credit allocation\n- Full published app capability (your apps go live at `yourapp.emergent.host`)\n- Support for [custom domains](/custom-domain)\n- Access to all core platform features\n\nStandard is the right choice when you're ready to ship real applications, need your work publicly accessible, or want consistent monthly credits for ongoing development.\n\n## Pro plan\n\nThe Pro plan is built for **teams, businesses, and power users** who need maximum capacity and priority treatment. It includes:\n\n- The highest monthly credit allocation\n- Priority support with faster response times\n- Early access to new features and capabilities\n- All Standard features, plus advanced configurations\n\nChoose Pro when you're scaling production apps, running a development team, or need guaranteed availability and support.\n\n<Info>\nBoth Standard and Pro support [custom agents](/custom-agents) and [AI media generation](/ai-media-generation-image-video-audio). Credit usage varies by job complexity - see [What is a Job?](/what-is-a-job) for details.\n</Info>\n\n## Choosing the right plan\n\n<Steps>\n<Step title=\"Evaluate your published app needs\">\nIf you need to publish apps to production, you must choose Standard or Pro. Free tier is workspace-only.\n</Step>\n\n<Step title=\"Estimate your monthly credit usage\">\nConsider how many apps you'll build, how frequently you'll iterate, and whether you need [Wingman](/what-is-wingman) assistance. Larger, more complex jobs consume more credits.\n</Step>\n\n<Step title=\"Factor in team size and support requirements\">\nSolo developers typically do well on Standard. Teams, agencies, or businesses benefit from Pro's priority support and higher limits.\n</Step>\n</Steps>\n\n## Bulk credits & custom pricing\n\n<Callout type=\"tip\" title=\"Need more credits?\">\nIf your usage exceeds your plan's monthly allocation, you can **purchase bulk credits** with custom pricing tailored to your volume. This option is available to Standard and Pro customers - contact sales to discuss your needs.\n</Callout>\n\nBulk credit purchases are one-time add-ons that supplement your monthly plan. They're ideal for:\n\n- Seasonal spikes in development activity\n- Large migration or refactoring projects\n- Agencies managing multiple client apps\n\n\n## Credit management\n\nAll plans follow the same credit lifecycle rules:\n\n- Credits recharge monthly on your billing date\n- Unused **subscription** credits **do not roll over**, they expire at cycle end; purchased top-up credits never expire\n- You can monitor usage in real-time from your workspace dashboard\n\nFor details on expiry, top-ups, and recharge timing, see [Managing credit usage](/managing-credit-usage).\n\n<Warning>\nPublishing, testing, and generating media with AI agents all consume credits. Plan your monthly allocation carefully, especially if you're building multiple apps or iterating frequently.\n</Warning>","published_title":"Plans & the free tier","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"7f415666-0009-41dc-afe1-78f4bdba6372","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Managing credit usage","slug":"managing-credit-usage","content":"## What credits are\n\nCredits are Emergent's usage currency. Every action the platform takes on your behalf - generating code, running tests, publishing to the cloud, calling external APIs - consumes a small number of credits from your account balance. This metered approach keeps costs predictable and aligns what you pay with what you actually use.\n\nThe basics:\n\n- **One combined balance**: all agent runs consume Emergent Credits from a single balance, whether you use Emergent's built-in LLM infrastructure or the Universal LLM Key. \n- **Where to see it**: your current balance shows in the top-right corner of the workspace. For the detailed usage breakdown, go to **Account Settings → Credit Usage** (see [Monitoring usage](#monitoring-usage) below).\n\n---\n\n## What consumes credits\n\nCredits are deducted whenever the platform performs work:\n\n- **Code generation**: each time you send a prompt and Emergent's agents write, refactor or extend your app's code, credits are consumed. The amount scales with the scope of the change and the complexity of the files touched.\n\n- **Testing & validation**: automated tests - unit tests, integration checks, visual regression scans - all consume credits. The more comprehensive the test suite, the higher the cost per run.\n\n- **Cloud publishes**: publishing tiers carry fixed monthly fees (Starter · Launch · Grow · Scale · Elite). Republishes, replacements, and rollbacks are free of charge. Publishing your project as a separate or new app starts a new publish and consumes credits at its own tier fee.\n\n- **Integrations & scheduled tasks**: calling third-party APIs, scheduling cron jobs and running background workers through [Integrations & scheduled tasks](/integrations-scheduled-tasks) each deduct credits based on execution duration and frequency.\n\n- **LLM calls via the Universal Key**: if you use [the Universal LLM Key](/the-universal-llm-key) to let your *app* call language models at runtime, those API calls are billed through your Emergent credit balance, not your personal OpenAI or Anthropic account.\n\n<Note>\nThe **Universal LLM Key** (`sk-emergent-` prefix) is an Emergent-managed key that gives you access to 44+ models across 7 providers at platform per-token rates with no markup. It is funded from your Emergent credits balance: auto-recharge transfers from your main balance when it drops below 5 credits. There is no separate external billing through your own provider account.\n</Note>\n\n<Info title=\"Maxx mode uses more credits\">\nWhen you enable **Maxx mode** (the toggle in the prompt bar), Emergent agents plan more thoroughly, explore alternative implementations and run deeper validation passes. This produces higher-quality results but consumes significantly more credits than a standard prompt.\n</Info>\n\n---\n\n## Credit types, expiry & monthly reset\n\nCredits on Emergent operate on a **monthly billing cycle**. At the start of each cycle (the day your plan renews), your credit balance refills to the full amount included in your plan - you do not accumulate unused subscription credits from previous months.\n\nFor example, if your plan includes 500 credits per month and you use only 200, the remaining 300 do not roll over. Your balance refills to 500 on the renewal date.\n\nEmergent has three kinds of credits, and expiry works differently for each:\n\n| Credit type | Rolls over? | Expires? |\n|---|---|---|\n| Monthly subscription credits | No, refill to cap each cycle | Yes, cleared at renewal |\n| Purchased top-up credits | Yes, permanent | Never |\n| Promotional / boost credits | Yes, until expiry | Yes, expiry date shown |\n\n<Tip>\nIf you regularly have subscription credits left over, consider downgrading to a smaller plan and topping up only when needed for larger projects. Check your remaining credits in **Account Settings → Credit Usage**, and your renewal date in ** Manage plan** in the profile icon menu.\n</Tip>\n\n---\n\n## Topping up\n\nYou can **add credits anytime** without waiting for your monthly reset. Top-up packs are purchased in your billing settings and added to your single combined balance instantly.\n\n**Available pack sizes include**: 250 credits ($50) up to 10,000+ credits ($2,000), with custom volumes also available.\n\n<Steps>\n<Step title=\"Open billing settings\">\nClick your avatar in the workspace header, then select **Billing & Usage**.\n</Step>\n\n<Step title=\"Purchase a credit pack\">\nChoose a credit pack size. Payment is region-routed: Stripe, Razorpay (India), PagBrasil (Brazil), Paddle, or RevenueCat depending on your location.\n</Step>\n\n<Step title=\"Credits appear instantly\">\nYour new balance updates within seconds - you can see it in the top-right corner of the workspace. Purchased top-up credits never expire.\n</Step>\n</Steps>\n\nGood to know:\n\n- **You can mix credit types**: the platform always spends expiring credits first to maximize your value.\n- **Top-up credits are non-refundable**: check your current balance and renewal date before deciding whether to top up or wait for your next cycle.\n- **High-volume teams**: contact support to discuss annual prepaid bundles with volume discounts.\n\n---\n\n## Running low & hitting zero\n\nEmergent monitors your credit balance in real time as agents work on your app. A **low-balance notice** appears in-app when you drop below 5 credits, giving you time to top up before hitting zero.\n\n**If your balance reaches zero mid-build**, the platform pauses all active generation, builds and publishes immediately. You'll see a notification in the workspace, and the build stops wherever it left off: code already written remains saved, but the agents won't continue - and your app won't go live - until you top up. There is no overage billing.\n\n<Info title=\"No partial-charge surprises\">\nYou are only charged for the work that completes. If a build stops halfway due to insufficient credits, you pay only for the tokens consumed up to that point.\n</Info>\n\nOnce you **add more credits** (via the billing page or automatic renewal), the build auto-resumes and the agents pick up context from where they stopped. No work is lost.\n\n### Renewal & negative balance\n\nWith an active plan, your balance is topped up automatically at the start of each billing cycle.\n\n<Warning title=\"Negative balance and app takedown risk\">\nIf your account has **fewer than 50 credits at renewal time, the platform may allow your balance to go negative** to complete an in-flight build. This grace period is temporary.\n\nWhen Emergent's next billing check runs (typically within 24-48 hours), accounts with a negative balance will be flagged. If the balance remains negative, your published app may be taken down until you recharge and bring the account back into positive territory.\n</Warning>\n\n**To avoid this scenario:**\n\n- **Monitor closely near renewal**: watch your credit usage if you're near the end of a billing cycle.\n- **Set up low-balance email alerts** (if available in your plan) so you're notified before hitting zero.\n- **Top up before large builds**: manually add credits before starting a big build if your remaining balance is tight.\n\n<Info title=\"Renewal indicator\">\nIf a plan renewal payment does not come in, a red banner appears at the top of the screen with a countdown of days left and a \"Renew Plan →\" link to retry the payment. Watch out for this indicator (shown for Stripe payment gateway users only).\n</Info>\n\n---\n\n## Estimating cost & capping spend\n\nThe cost of a single prompt varies widely - from a handful of credits for a small UI tweak to hundreds for a full feature with tests. Large or complex builds can consume hundreds or even thousands of credits depending on the scope of your prompts, the number of files generated, and the iterations required. The platform shows an **estimated cost** before committing large changes, so you're never surprised.\n\n<Tip title=\"Cap your spending with a per-prompt limit\">\nIn **Settings → Billing**, you can set a **maximum credits per prompt**. If an agent's plan would exceed that ceiling, Emergent will ask you to approve the overage or break the task into smaller steps. This guardrail prevents runaway costs on complex requests.\n</Tip>\n\n### Quick estimation tips\n\n- **Start small**: build a minimal version of one feature first, note the credit cost, then extrapolate for additional features.\n- **Review past builds**: check your billing history or workspace logs to see how many credits similar prompts consumed.\n- **Ask in smaller chunks**: breaking a big request into multiple focused prompts often gives you better control and visibility into incremental costs.\n- **Test with a prototype**: if you're unsure how expensive a new idea will be, scaffold a simple proof-of-concept in a separate app, validate cost and feasibility, then commit to the full build.\n\n### When to top up in advance\n\nIf you're planning a **major refactor**, **adding a complex backend integration**, or **converting between web and mobile** (see [Web to Mobile conversion](/web-mobile-conversion-canonical)), consider topping up your account beforehand. Running out mid-build can disrupt agent context and require you to re-explain requirements.\n\nFor ongoing projects, many users find that enabling auto-renewal and a comfortable monthly credit allowance provides the smoothest experience: no interruptions, and you stay in flow. If you regularly work on large, multi-file features, consider a higher-tier plan with a more generous monthly credit allowance and lower per-credit rate.\n\n---\n\n## Monitoring usage\n\nYour current balance is always visible in the top-right corner of the workspace. For the full picture, open **Account Settings → Credit Usage**: it shows your consumption by category (agent runs, published versions, Universal Key calls, and more).\n","order":44,"parent_id":null,"icon":"gauge","description":"What credits are, what consumes them, expiry and monthly reset, topping up, running low, and how to estimate and cap spending.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T09:09:10.158131+00:00","published_at":"2026-09-25T09:09:10.158131+00:00","published_content":"## What credits are\n\nCredits are Emergent's usage currency. Every action the platform takes on your behalf - generating code, running tests, publishing to the cloud, calling external APIs - consumes a small number of credits from your account balance. This metered approach keeps costs predictable and aligns what you pay with what you actually use.\n\nThe basics:\n\n- **One combined balance**: all agent runs consume Emergent Credits from a single balance, whether you use Emergent's built-in LLM infrastructure or the Universal LLM Key. \n- **Where to see it**: your current balance shows in the top-right corner of the workspace. For the detailed usage breakdown, go to **Account Settings → Credit Usage** (see [Monitoring usage](#monitoring-usage) below).\n\n---\n\n## What consumes credits\n\nCredits are deducted whenever the platform performs work:\n\n- **Code generation**: each time you send a prompt and Emergent's agents write, refactor or extend your app's code, credits are consumed. The amount scales with the scope of the change and the complexity of the files touched.\n\n- **Testing & validation**: automated tests - unit tests, integration checks, visual regression scans - all consume credits. The more comprehensive the test suite, the higher the cost per run.\n\n- **Cloud publishes**: publishing tiers carry fixed monthly fees (Starter · Launch · Grow · Scale · Elite). Republishes, replacements, and rollbacks are free of charge. Publishing your project as a separate or new app starts a new publish and consumes credits at its own tier fee.\n\n- **Integrations & scheduled tasks**: calling third-party APIs, scheduling cron jobs and running background workers through [Integrations & scheduled tasks](/integrations-scheduled-tasks) each deduct credits based on execution duration and frequency.\n\n- **LLM calls via the Universal Key**: if you use [the Universal LLM Key](/the-universal-llm-key) to let your *app* call language models at runtime, those API calls are billed through your Emergent credit balance, not your personal OpenAI or Anthropic account.\n\n<Note>\nThe **Universal LLM Key** (`sk-emergent-` prefix) is an Emergent-managed key that gives you access to 44+ models across 7 providers at platform per-token rates with no markup. It is funded from your Emergent credits balance: auto-recharge transfers from your main balance when it drops below 5 credits. There is no separate external billing through your own provider account.\n</Note>\n\n<Info title=\"Maxx mode uses more credits\">\nWhen you enable **Maxx mode** (the toggle in the prompt bar), Emergent agents plan more thoroughly, explore alternative implementations and run deeper validation passes. This produces higher-quality results but consumes significantly more credits than a standard prompt.\n</Info>\n\n---\n\n## Credit types, expiry & monthly reset\n\nCredits on Emergent operate on a **monthly billing cycle**. At the start of each cycle (the day your plan renews), your credit balance refills to the full amount included in your plan - you do not accumulate unused subscription credits from previous months.\n\nFor example, if your plan includes 500 credits per month and you use only 200, the remaining 300 do not roll over. Your balance refills to 500 on the renewal date.\n\nEmergent has three kinds of credits, and expiry works differently for each:\n\n| Credit type | Rolls over? | Expires? |\n|---|---|---|\n| Monthly subscription credits | No, refill to cap each cycle | Yes, cleared at renewal |\n| Purchased top-up credits | Yes, permanent | Never |\n| Promotional / boost credits | Yes, until expiry | Yes, expiry date shown |\n\n<Tip>\nIf you regularly have subscription credits left over, consider downgrading to a smaller plan and topping up only when needed for larger projects. Check your remaining credits in **Account Settings → Credit Usage**, and your renewal date in ** Manage plan** in the profile icon menu.\n</Tip>\n\n---\n\n## Topping up\n\nYou can **add credits anytime** without waiting for your monthly reset. Top-up packs are purchased in your billing settings and added to your single combined balance instantly.\n\n**Available pack sizes include**: 250 credits ($50) up to 10,000+ credits ($2,000), with custom volumes also available.\n\n<Steps>\n<Step title=\"Open billing settings\">\nClick your avatar in the workspace header, then select **Billing & Usage**.\n</Step>\n\n<Step title=\"Purchase a credit pack\">\nChoose a credit pack size. Payment is region-routed: Stripe, Razorpay (India), PagBrasil (Brazil), Paddle, or RevenueCat depending on your location.\n</Step>\n\n<Step title=\"Credits appear instantly\">\nYour new balance updates within seconds - you can see it in the top-right corner of the workspace. Purchased top-up credits never expire.\n</Step>\n</Steps>\n\nGood to know:\n\n- **You can mix credit types**: the platform always spends expiring credits first to maximize your value.\n- **Top-up credits are non-refundable**: check your current balance and renewal date before deciding whether to top up or wait for your next cycle.\n- **High-volume teams**: contact support to discuss annual prepaid bundles with volume discounts.\n\n---\n\n## Running low & hitting zero\n\nEmergent monitors your credit balance in real time as agents work on your app. A **low-balance notice** appears in-app when you drop below 5 credits, giving you time to top up before hitting zero.\n\n**If your balance reaches zero mid-build**, the platform pauses all active generation, builds and publishes immediately. You'll see a notification in the workspace, and the build stops wherever it left off: code already written remains saved, but the agents won't continue - and your app won't go live - until you top up. There is no overage billing.\n\n<Info title=\"No partial-charge surprises\">\nYou are only charged for the work that completes. If a build stops halfway due to insufficient credits, you pay only for the tokens consumed up to that point.\n</Info>\n\nOnce you **add more credits** (via the billing page or automatic renewal), the build auto-resumes and the agents pick up context from where they stopped. No work is lost.\n\n### Renewal & negative balance\n\nWith an active plan, your balance is topped up automatically at the start of each billing cycle.\n\n<Warning title=\"Negative balance and app takedown risk\">\nIf your account has **fewer than 50 credits at renewal time, the platform may allow your balance to go negative** to complete an in-flight build. This grace period is temporary.\n\nWhen Emergent's next billing check runs (typically within 24-48 hours), accounts with a negative balance will be flagged. If the balance remains negative, your published app may be taken down until you recharge and bring the account back into positive territory.\n</Warning>\n\n**To avoid this scenario:**\n\n- **Monitor closely near renewal**: watch your credit usage if you're near the end of a billing cycle.\n- **Set up low-balance email alerts** (if available in your plan) so you're notified before hitting zero.\n- **Top up before large builds**: manually add credits before starting a big build if your remaining balance is tight.\n\n<Info title=\"Renewal indicator\">\nIf a plan renewal payment does not come in, a red banner appears at the top of the screen with a countdown of days left and a \"Renew Plan →\" link to retry the payment. Watch out for this indicator (shown for Stripe payment gateway users only).\n</Info>\n\n---\n\n## Estimating cost & capping spend\n\nThe cost of a single prompt varies widely - from a handful of credits for a small UI tweak to hundreds for a full feature with tests. Large or complex builds can consume hundreds or even thousands of credits depending on the scope of your prompts, the number of files generated, and the iterations required. The platform shows an **estimated cost** before committing large changes, so you're never surprised.\n\n<Tip title=\"Cap your spending with a per-prompt limit\">\nIn **Settings → Billing**, you can set a **maximum credits per prompt**. If an agent's plan would exceed that ceiling, Emergent will ask you to approve the overage or break the task into smaller steps. This guardrail prevents runaway costs on complex requests.\n</Tip>\n\n### Quick estimation tips\n\n- **Start small**: build a minimal version of one feature first, note the credit cost, then extrapolate for additional features.\n- **Review past builds**: check your billing history or workspace logs to see how many credits similar prompts consumed.\n- **Ask in smaller chunks**: breaking a big request into multiple focused prompts often gives you better control and visibility into incremental costs.\n- **Test with a prototype**: if you're unsure how expensive a new idea will be, scaffold a simple proof-of-concept in a separate app, validate cost and feasibility, then commit to the full build.\n\n### When to top up in advance\n\nIf you're planning a **major refactor**, **adding a complex backend integration**, or **converting between web and mobile** (see [Web to Mobile conversion](/web-mobile-conversion-canonical)), consider topping up your account beforehand. Running out mid-build can disrupt agent context and require you to re-explain requirements.\n\nFor ongoing projects, many users find that enabling auto-renewal and a comfortable monthly credit allowance provides the smoothest experience: no interruptions, and you stay in flow. If you regularly work on large, multi-file features, consider a higher-tier plan with a more generous monthly credit allowance and lower per-credit rate.\n\n---\n\n## Monitoring usage\n\nYour current balance is always visible in the top-right corner of the workspace. For the full picture, open **Account Settings → Credit Usage**: it shows your consumption by category (agent runs, published versions, Universal Key calls, and more).\n","published_title":"Managing credit usage","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"33696f16-ce04-47b9-9faa-3f76125f7646","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Referrals & Affiliates program","slug":"referrals-partners-program","content":"## Overview\n\nEmergent rewards you for bringing new users to the platform and offers partnership opportunities for content creators and communities. Three programs are available depending on your plan and audience size:\n\n- **Referral program** - earn credits when friends sign up and become paid users\n- **Partners program** - earn 20% recurring cash commissions on subscriptions\n- **Secret Perks** - exclusive Pro-only benefits and early access\n\n<Note title=\"Paid users only\">\nAll referral and partner benefits require an active paid Emergent plan (Standard or Pro). Free-tier users cannot earn referral credits or partner commissions.\n</Note>\n\n---\n\n## Referral program\n\nShare your unique referral link with friends and colleagues. When a referee signs up, verifies their email and upgrades to any paid plan, you both receive credits.\n\n### How it works\n\n<Steps>\n<Step title=\"Find your referral link\">\nNavigate to **Settings → Referrals** in the Emergent workspace. Copy your unique link.\n</Step>\n\n<Step title=\"Share your link\">\nSend the link to friends, post it in your community or share on social media.\n</Step>\n\n<Step title=\"Earn credits when they upgrade\">\nWhen a referee signs up via your link, they receive **5 bonus credits on signup**. When the referee subscribes to a paid plan, you receive **50 credits**.\n</Step>\n</Steps>\n\n### Eligibility & limits\n\n| Requirement | Details |\n|-------------|---------|\n| **Referrer** | Must have an active paid plan (Standard or Pro) |\n\n| **Referee** | Must be a new user who has not previously held a paid plan |\n| **Credit award** | 50 credits to referrer, 5 credits to referee |\n| **Total cap** | Referral credits are capped at 20 referrals / $200 of credits in total |\n| **Expiry** | Referral credits follow the same expiry rules as plan credits - see [Managing credit usage](/managing-credit-usage) |\n\n<Warning title=\"Fraudulent referrals\">\nSelf-referrals, duplicate accounts and coordinated sign-ups to farm credits violate the terms of service and will result in account suspension and forfeiture of all referral credits.\n</Warning>\n\nReferral credits appear in your workspace balance within minutes of the referee's first paid subscription charge.\n\n---\n\n# Affiliate program (replacement for the \"Partners program\" section)\n\n*Reviewed final (2026-09-17) - wording follows the Affiliate Partner Guide. Replaces the current \"Partners program\" section on the Referrals & Affiliate program page.*\n\n---\n\n## Affiliate program\n\nThe Affiliate program is for content creators, educators, community leaders, agencies, ad networks and affiliate networks who can help more people discover Emergent. Affiliates earn cash commissions on the paying subscribers they refer - and there is no cap on the number of referrals: the more subscribers you bring in, the more you earn.\n\n### The affiliate process\n\n**Step 1 - Join & get your link.** Sign up via your Emergent contact or the affiliate portal at [emergent.sh/affiliates](https://emergent.sh/affiliates). You'll receive a unique tracked link and dashboard access.\n\n**Step 2 - Share your link.** Place your affiliate link wherever your audience takes action - email newsletters, review pages, websites, resource lists. Every click is tracked to your account. Always use your own unique tracked link, and use a link shortener to keep it clean.\n\n**Step 3 - Referral signs up & subscribes.** When someone signs up through your link and takes out a paid subscription, you earn commission under the payout structure agreed for your partnership.\n\n**Step 4 - Get paid, keep growing.** Earnings are tracked in real time on your dashboard.\n\n### Commission structure\n\nEmergent offers different payout structures. Your programme manager will confirm which one applies to your partnership based on your audience, traffic source and region:\n\n- **Revenue share** - you earn 20% or 30% of the full subscription cost, including any top-ups, for the first 6 months from the customer's sign-up date. Which rate applies is agreed with the Emergent team based on your audience, traffic quality and volume.\n- **Flat CPA** - a fixed payout for every qualified paying customer you refer, paid per conversion rather than as a share of revenue. Flat CPA rates differ by geography, because subscription value and customer lifetime vary by region - your programme manager will confirm the rates that apply to the markets you drive traffic from.\n\nAll payout structures stack with leaderboard bonuses.\n\n### The leaderboard - earn bonuses on top\n\nEmergent's Game Room runs monthly leaderboard contests where partners compete on the paid customers they drive, and every bonus sits entirely on top of your standard commission. Bonuses are reworked every campaign, so there is always a fresh pool to win.\n\nHow to take part:\n\n- Each campaign is catered to a specific set of partners, so **entry is by invitation** - speak to your programme manager to be considered.\n- **You must log into the leaderboard to be eligible** for any bonus: partners who drive conversions but never sign in do not qualify.\n- See the current campaign and the full payout mechanics at [earn-more-zone.emergent.host/podium](https://earn-more-zone.emergent.host/podium) and open the How to Earn section for the complete breakdown of ranking tiers, the daily ladder and the weekly milestones.\n\n### Strictly prohibited\n\nBidding on Emergent brand keywords on Google Ads. Fraudulent activity of any kind, including commission fabrication, fake referrals, bot traffic, cookie stuffing, or manipulation of tracking links. Violations result in immediate removal from the programme, forfeiture of unpaid commissions, and disqualification from all leaderboard bonuses.\n\n### Media kit & message drafts\n\nEmergent provides approved creative assets and ready-to-use copy - brand logos, creatives, and banner images for websites and newsletters. Request access from your programme manager.\n\n### Getting started\n\n1. Sign up via your Emergent contact or the official affiliate portal: [emergent.sh/affiliates](https://emergent.sh/affiliates).\n2. Receive your unique tracked affiliate link.\n3. Share your link with your audience - newsletters, websites, review pages.\n4. Monitor referrals and commissions on your affiliate dashboard.\n5. Contact your programme manager for assets, questions, or support.\n\n## Frequently asked questions\n\n<AccordionGroup>\n<Accordion title=\"Can I use referral credits and affiliate commissions together?\">\nYes. Referral credits apply to friends and colleagues you introduce casually; affiliate commissions apply to paying subscribers acquired through your affiliate link. The programs can run in parallel as long as you meet the eligibility requirements for each.\n</Accordion>\n\n<Accordion title=\"Do referral credits stack with plan credits?\">\nReferral credits are added to your workspace balance and consumed alongside plan credits. They follow the same expiry and recharge rules - see [Managing credit usage](/managing-credit-usage) for details.\n</Accordion>\n\n<Accordion title=\"Are there geographic restrictions?\">\nReferral credits are available worldwide. Affiliate payout structures vary by region: flat CPA rates differ by geography because subscription value and customer lifetime vary, so your programme manager will confirm the rates and payout details that apply to the markets you drive traffic from.\n</Accordion>\n\n<Accordion title=\"Can I become an affiliate if I only have a small audience?\">\nYes - there is no minimum audience size to sign up at [emergent.sh/affiliates](https://emergent.sh/affiliates). Your payout structure is agreed with the Emergent team based on your audience, traffic quality and volume, so a highly engaged niche community can do well. Leaderboard campaigns are a separate, invitation-only layer on top.\n</Accordion>\n</AccordionGroup>\n---\n\n## Quick links\n\n<CardGroup cols={2}>\n<Card title=\"Referrals dashboard\" icon=\"link\" href=\"/settings/referrals\">\nCopy your referral link and track sign-ups in real time\n</Card>\n\n<Card title=\"Join the Affiliate program\" icon=\"handshake\" href=\"https://emergent.sh/affiliates\">\nSign up to get your unique tracked affiliate link and dashboard access\n</Card>\n\n<Card title=\"Plans & pricing\" icon=\"credit-card\" href=\"/plans\">\nReview plan tiers and what each includes\n</Card>\n\n<Card title=\"Managing credit usage\" icon=\"clock\" href=\"/managing-credit-usage\">\nUnderstand how referral credits expire and recharge\n</Card>\n</CardGroup>","order":47,"parent_id":null,"icon":"users","description":"Referral program (50 credits per referral, referee gets 5, paid users only, with caps), the separate Partners program (20% cash commission via Wise), and Pro-only Secret Perks.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:45.458907+00:00","published_at":"2026-09-22T06:20:45.458907+00:00","published_content":"## Overview\n\nEmergent rewards you for bringing new users to the platform and offers partnership opportunities for content creators and communities. Three programs are available depending on your plan and audience size:\n\n- **Referral program** - earn credits when friends sign up and become paid users\n- **Partners program** - earn 20% recurring cash commissions on subscriptions\n- **Secret Perks** - exclusive Pro-only benefits and early access\n\n<Note title=\"Paid users only\">\nAll referral and partner benefits require an active paid Emergent plan (Standard or Pro). Free-tier users cannot earn referral credits or partner commissions.\n</Note>\n\n---\n\n## Referral program\n\nShare your unique referral link with friends and colleagues. When a referee signs up, verifies their email and upgrades to any paid plan, you both receive credits.\n\n### How it works\n\n<Steps>\n<Step title=\"Find your referral link\">\nNavigate to **Settings → Referrals** in the Emergent workspace. Copy your unique link.\n</Step>\n\n<Step title=\"Share your link\">\nSend the link to friends, post it in your community or share on social media.\n</Step>\n\n<Step title=\"Earn credits when they upgrade\">\nWhen a referee signs up via your link, they receive **5 bonus credits on signup**. When the referee subscribes to a paid plan, you receive **50 credits**.\n</Step>\n</Steps>\n\n### Eligibility & limits\n\n| Requirement | Details |\n|-------------|---------|\n| **Referrer** | Must have an active paid plan (Standard or Pro) |\n\n| **Referee** | Must be a new user who has not previously held a paid plan |\n| **Credit award** | 50 credits to referrer, 5 credits to referee |\n| **Total cap** | Referral credits are capped at 20 referrals / $200 of credits in total |\n| **Expiry** | Referral credits follow the same expiry rules as plan credits - see [Managing credit usage](/managing-credit-usage) |\n\n<Warning title=\"Fraudulent referrals\">\nSelf-referrals, duplicate accounts and coordinated sign-ups to farm credits violate the terms of service and will result in account suspension and forfeiture of all referral credits.\n</Warning>\n\nReferral credits appear in your workspace balance within minutes of the referee's first paid subscription charge.\n\n---\n\n# Affiliate program (replacement for the \"Partners program\" section)\n\n*Reviewed final (2026-09-17) - wording follows the Affiliate Partner Guide. Replaces the current \"Partners program\" section on the Referrals & Affiliate program page.*\n\n---\n\n## Affiliate program\n\nThe Affiliate program is for content creators, educators, community leaders, agencies, ad networks and affiliate networks who can help more people discover Emergent. Affiliates earn cash commissions on the paying subscribers they refer - and there is no cap on the number of referrals: the more subscribers you bring in, the more you earn.\n\n### The affiliate process\n\n**Step 1 - Join & get your link.** Sign up via your Emergent contact or the affiliate portal at [emergent.sh/affiliates](https://emergent.sh/affiliates). You'll receive a unique tracked link and dashboard access.\n\n**Step 2 - Share your link.** Place your affiliate link wherever your audience takes action - email newsletters, review pages, websites, resource lists. Every click is tracked to your account. Always use your own unique tracked link, and use a link shortener to keep it clean.\n\n**Step 3 - Referral signs up & subscribes.** When someone signs up through your link and takes out a paid subscription, you earn commission under the payout structure agreed for your partnership.\n\n**Step 4 - Get paid, keep growing.** Earnings are tracked in real time on your dashboard.\n\n### Commission structure\n\nEmergent offers different payout structures. Your programme manager will confirm which one applies to your partnership based on your audience, traffic source and region:\n\n- **Revenue share** - you earn 20% or 30% of the full subscription cost, including any top-ups, for the first 6 months from the customer's sign-up date. Which rate applies is agreed with the Emergent team based on your audience, traffic quality and volume.\n- **Flat CPA** - a fixed payout for every qualified paying customer you refer, paid per conversion rather than as a share of revenue. Flat CPA rates differ by geography, because subscription value and customer lifetime vary by region - your programme manager will confirm the rates that apply to the markets you drive traffic from.\n\nAll payout structures stack with leaderboard bonuses.\n\n### The leaderboard - earn bonuses on top\n\nEmergent's Game Room runs monthly leaderboard contests where partners compete on the paid customers they drive, and every bonus sits entirely on top of your standard commission. Bonuses are reworked every campaign, so there is always a fresh pool to win.\n\nHow to take part:\n\n- Each campaign is catered to a specific set of partners, so **entry is by invitation** - speak to your programme manager to be considered.\n- **You must log into the leaderboard to be eligible** for any bonus: partners who drive conversions but never sign in do not qualify.\n- See the current campaign and the full payout mechanics at [earn-more-zone.emergent.host/podium](https://earn-more-zone.emergent.host/podium) and open the How to Earn section for the complete breakdown of ranking tiers, the daily ladder and the weekly milestones.\n\n### Strictly prohibited\n\nBidding on Emergent brand keywords on Google Ads. Fraudulent activity of any kind, including commission fabrication, fake referrals, bot traffic, cookie stuffing, or manipulation of tracking links. Violations result in immediate removal from the programme, forfeiture of unpaid commissions, and disqualification from all leaderboard bonuses.\n\n### Media kit & message drafts\n\nEmergent provides approved creative assets and ready-to-use copy - brand logos, creatives, and banner images for websites and newsletters. Request access from your programme manager.\n\n### Getting started\n\n1. Sign up via your Emergent contact or the official affiliate portal: [emergent.sh/affiliates](https://emergent.sh/affiliates).\n2. Receive your unique tracked affiliate link.\n3. Share your link with your audience - newsletters, websites, review pages.\n4. Monitor referrals and commissions on your affiliate dashboard.\n5. Contact your programme manager for assets, questions, or support.\n\n## Frequently asked questions\n\n<AccordionGroup>\n<Accordion title=\"Can I use referral credits and affiliate commissions together?\">\nYes. Referral credits apply to friends and colleagues you introduce casually; affiliate commissions apply to paying subscribers acquired through your affiliate link. The programs can run in parallel as long as you meet the eligibility requirements for each.\n</Accordion>\n\n<Accordion title=\"Do referral credits stack with plan credits?\">\nReferral credits are added to your workspace balance and consumed alongside plan credits. They follow the same expiry and recharge rules - see [Managing credit usage](/managing-credit-usage) for details.\n</Accordion>\n\n<Accordion title=\"Are there geographic restrictions?\">\nReferral credits are available worldwide. Affiliate payout structures vary by region: flat CPA rates differ by geography because subscription value and customer lifetime vary, so your programme manager will confirm the rates and payout details that apply to the markets you drive traffic from.\n</Accordion>\n\n<Accordion title=\"Can I become an affiliate if I only have a small audience?\">\nYes - there is no minimum audience size to sign up at [emergent.sh/affiliates](https://emergent.sh/affiliates). Your payout structure is agreed with the Emergent team based on your audience, traffic quality and volume, so a highly engaged niche community can do well. Leaderboard campaigns are a separate, invitation-only layer on top.\n</Accordion>\n</AccordionGroup>\n---\n\n## Quick links\n\n<CardGroup cols={2}>\n<Card title=\"Referrals dashboard\" icon=\"link\" href=\"/settings/referrals\">\nCopy your referral link and track sign-ups in real time\n</Card>\n\n<Card title=\"Join the Affiliate program\" icon=\"handshake\" href=\"https://emergent.sh/affiliates\">\nSign up to get your unique tracked affiliate link and dashboard access\n</Card>\n\n<Card title=\"Plans & pricing\" icon=\"credit-card\" href=\"/plans\">\nReview plan tiers and what each includes\n</Card>\n\n<Card title=\"Managing credit usage\" icon=\"clock\" href=\"/managing-credit-usage\">\nUnderstand how referral credits expire and recharge\n</Card>\n</CardGroup>","published_title":"Referrals & Affiliates program","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"a08d9b95-7ce1-4dbb-bedf-924405e43eb5","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Payment methods & regional billing","slug":"payment-methods-regional-billing","content":"## Overview\n\nEmergent routes your credit purchase through the payment processor best suited to your country and currency. We support **Stripe**, **Razorpay**, **PagBrasil**, **Paddle**, and **RevenueCat** depending on where you are and how you pay.\n\nAll credits share a **single combined balance**. We do **not** store card details on our servers, all tokenization and secure storage happens at the processor.\n\n---\n\n## Supported payment processors\n\n<CardGroup cols={2}>\n  <Card title=\"Stripe\" icon=\"credit-card\" href=\"/stripe\">\n    Global coverage: cards, Apple Pay, Google Pay, bank transfers in 40+ countries. Also handles crypto checkout.\n  </Card>\n  <Card title=\"Razorpay\" icon=\"building-columns\" href=\"/razorpay\">\n    India-specific: UPI, Netbanking, cards, wallets. INR-optimized.\n  </Card>\n  <Card title=\"PagBrasil\" icon=\"landmark\">\n    Brazil: Pix, boleto, local cards. BRL transactions.\n  </Card>\n  <Card title=\"Paddle\" icon=\"globe\">\n    Merchant-of-record model; always processes in USD and handles sales tax automatically.\n  </Card>\n</CardGroup>\n\nWhen you click **Buy Credits**, Emergent chooses the processor based on:\n\n- **Your IP geolocation** and browser locale.\n- **Your region** (USD, INR, BRL, KRW, EUR, GBP display currencies).\n- **Regulatory fit**: some processors are better licensed for certain regions.\n\n<Note>\nYou cannot manually pick a processor. If you need to change payment gateway, contact support at **support@emergent.sh**.\n</Note>\n\n\n<Warning>\nThe **Buy Credits** page in your workspace shows the live, region-specific price including any applicable taxes or gateway surcharges. All purchases add to your single combined credit balance regardless of the currency used.\n</Warning>\n\nSee [Managing credit usage](/managing-credit-usage) for usage mechanics.\n\n---\n\n## How payment routing works\n\n<Steps>\n  <Step title=\"You click Buy Credits\">\n    The platform reads your IP, browser `Accept-Language`, and region to determine the appropriate processor and display currency.\n  </Step>\n  <Step title=\"Processor is selected\">\n    Emergent routes you to the processor with the best local method support for your region. Gateway changes must go through **support@emergent.sh**.\n  </Step>\n  <Step title=\"You complete payment\">\n    You are redirected to the processor's hosted checkout (Stripe, Razorpay, etc.). Card details never touch our servers.\n  </Step>\n  <Step title=\"Credits land in your workspace\">\n    On successful webhook confirmation, credits appear in your single combined balance within seconds. If the webhook is delayed, credits may take up to 5 minutes.\n  </Step>\n</Steps>\n\n---\n\n## Legal entity names on your statement\n\nDepending on the processor and region, your bank or credit-card statement will show one of these:\n\n| Processor / Region | Statement descriptor |\n|--------------------|----------------------|\n| **Stripe (global)** | `Emergent` or `Emergent Labs Inc.` |\n| **Razorpay (India)** | `AGIONE TECHNOLOGIES PRIVATE LIMITED` or `RAZORPAY*EMERGENT` |\n| **PagBrasil (Brazil)** | `PAGBRASIL*EMERGENT` |\n| **Paddle** | `PADDLE.NET*EMERGENT` (Paddle always processes USD) |\n| **RevenueCat** | `REVENUECAT*EMERGENT` (mobile IAP receipts) |\n\n<Note>\nThe India-region legal entity is **AGIONE TECHNOLOGIES PRIVATE LIMITED**; the US entity is **Emergent Labs Inc.** Statements may show \"Emergent\" or \"Agione\".\n</Note>\n\n<Note>\nPaddle acts as **merchant of record** and always processes payments in **USD**, handling applicable sales tax automatically.\n</Note>\n\n---\n\n## No stored cards\n\nEmergent **does not store** your card number, CVV, or full PAN. When you pay:\n\n1. The processor (Stripe, Razorpay, etc.) tokenizes your card and returns a non-sensitive token.\n2. We store only the token, last four digits, brand (Visa/Mastercard), and expiry, for display purposes.\n3. Subsequent purchases use the same token; you can manage saved methods in **Settings → Billing**.\n\n<Info>\nIf you delete a saved payment method, you will be prompted to re-enter card details on your next purchase. No billing happens without your explicit \"Buy\" click.\n</Info>\n\n---\n\n## Cryptocurrency & stablecoins\n\nWe accept **USDC** and **USDT** (per Stripe availability) through **Stripe crypto checkout**. When you select crypto:\n\n- You complete payment through Stripe's hosted crypto checkout flow.\n- Credits are added to your combined balance after payment confirmation.\n\n- The exchange rate is locked for a limited window; if your transaction is not confirmed in time, contact support at **support@emergent.sh** for manual reconciliation.\n\n<Warning title=\"Testnet tokens are not accepted\">\nOnly send mainnet stablecoins through the Stripe crypto checkout. Sending unsupported tokens or sending to the wrong address will result in **permanent loss**, we cannot recover cross-chain or misdirected sends.\n</Warning>\n\n<AccordionGroup>\n  <Accordion title=\"Can I pay in Bitcoin or Ethereum?\">\n    Not currently. We accept only **USDC** and **USDT** (per Stripe availability) via Stripe crypto checkout.\n  </Accordion>\n</AccordionGroup>\n\n---\n\n## Refunds\n\nEmergent's refund policy: **purchased top-up credits are non-refundable**. However, if you cancel a subscription, you may be eligible for a prorated dollar refund of unused subscription credits (published app usage is subtracted first). To request a refund, contact **support@emergent.sh** with your transaction details.\n\n<Note>\nOnly subscription credits are eligible for prorated refunds on cancellation. Top-up (manually purchased) credits are non-refundable under any circumstance.\n</Note>\n\n---\n\n## Billing entity & taxes\n\nEmergent is a B2C platform. **GST/VAT invoices are not issued, and invoices cannot be edited after issuance.** Tax included in pricing varies by region and processor:\n\n- **Paddle** (USD): Handles applicable sales tax as merchant of record.\n- **Razorpay** (India): Taxes may be included; no GST invoice is provided.\n- **PagBrasil** (Brazil): Local taxes included in the BRL-equivalent rate.\n- **Stripe (EU/UK)**: VAT may be applied at checkout depending on region.\n\nIf you have specific tax documentation requirements, contact **support@emergent.sh**.\n\n---\n\n## Changing your payment gateway\n\nTo change your payment gateway or preferred processor, contact **support@emergent.sh**. Gateway changes are not self-service.\n\n<Note>\nAll credits, regardless of the currency or processor used at purchase, are added to your **single combined balance**. There are no separate per-currency balances.\n</Note>\n\n---\n\n## Common issues\n\n<AccordionGroup>\n  <Accordion title=\"Payment succeeded but credits didn't arrive\">\n    Webhook delays can take up to 5 minutes. Check **Settings → Billing → Transaction History**. If the status is \"Pending,\" wait. If \"Failed,\" contact **support@emergent.sh** with your transaction ID.\n  </Accordion>\n  <Accordion title=\"Card declined, what should I do?\">\n    Common causes: insufficient funds, 3DS challenge not completed, card not enabled for international transactions, or anti-fraud block. Try a different card or payment method (UPI, bank transfer, crypto). Contact **support@emergent.sh** if the issue persists.\n  </Accordion>\n  <Accordion title=\"Can I use a prepaid or virtual card?\">\n    Yes, as long as the card supports merchant authorizations. Some virtual cards block tokenization, test with a small purchase first.\n  </Accordion>\n  <Accordion title=\"Do you support purchase orders or NET-30 invoicing?\">\n\n    Enterprise plan customers may have access to PO/NET-30 billing arrangements. Contact **support@emergent.sh** for details.\n  </Accordion>\n</AccordionGroup>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n  <Card title=\"How credits work\" icon=\"coins\" href=\"/managing-credit-usage\">\n    Understand credit consumption, metering, and rate limits.\n  </Card>\n  <Card title=\"Managing credit usage\" icon=\"clock\" href=\"/managing-credit-usage\">\n    Expiry rules, auto-recharge, and low-balance alerts.\n  </Card>\n</CardGroup>","order":49,"parent_id":null,"icon":"tag","description":"How payment routing works across Stripe/Razorpay/PagBrasil/Paddle/RevenueCat, currency-specific credit rates (USD/INR/BRL/KRW), no stored cards, legal entity names on statements, a","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:46.864500+00:00","published_at":"2026-09-22T06:20:46.864500+00:00","published_content":"## Overview\n\nEmergent routes your credit purchase through the payment processor best suited to your country and currency. We support **Stripe**, **Razorpay**, **PagBrasil**, **Paddle**, and **RevenueCat** depending on where you are and how you pay.\n\nAll credits share a **single combined balance**. We do **not** store card details on our servers, all tokenization and secure storage happens at the processor.\n\n---\n\n## Supported payment processors\n\n<CardGroup cols={2}>\n  <Card title=\"Stripe\" icon=\"credit-card\" href=\"/stripe\">\n    Global coverage: cards, Apple Pay, Google Pay, bank transfers in 40+ countries. Also handles crypto checkout.\n  </Card>\n  <Card title=\"Razorpay\" icon=\"building-columns\" href=\"/razorpay\">\n    India-specific: UPI, Netbanking, cards, wallets. INR-optimized.\n  </Card>\n  <Card title=\"PagBrasil\" icon=\"landmark\">\n    Brazil: Pix, boleto, local cards. BRL transactions.\n  </Card>\n  <Card title=\"Paddle\" icon=\"globe\">\n    Merchant-of-record model; always processes in USD and handles sales tax automatically.\n  </Card>\n</CardGroup>\n\nWhen you click **Buy Credits**, Emergent chooses the processor based on:\n\n- **Your IP geolocation** and browser locale.\n- **Your region** (USD, INR, BRL, KRW, EUR, GBP display currencies).\n- **Regulatory fit**: some processors are better licensed for certain regions.\n\n<Note>\nYou cannot manually pick a processor. If you need to change payment gateway, contact support at **support@emergent.sh**.\n</Note>\n\n\n<Warning>\nThe **Buy Credits** page in your workspace shows the live, region-specific price including any applicable taxes or gateway surcharges. All purchases add to your single combined credit balance regardless of the currency used.\n</Warning>\n\nSee [Managing credit usage](/managing-credit-usage) for usage mechanics.\n\n---\n\n## How payment routing works\n\n<Steps>\n  <Step title=\"You click Buy Credits\">\n    The platform reads your IP, browser `Accept-Language`, and region to determine the appropriate processor and display currency.\n  </Step>\n  <Step title=\"Processor is selected\">\n    Emergent routes you to the processor with the best local method support for your region. Gateway changes must go through **support@emergent.sh**.\n  </Step>\n  <Step title=\"You complete payment\">\n    You are redirected to the processor's hosted checkout (Stripe, Razorpay, etc.). Card details never touch our servers.\n  </Step>\n  <Step title=\"Credits land in your workspace\">\n    On successful webhook confirmation, credits appear in your single combined balance within seconds. If the webhook is delayed, credits may take up to 5 minutes.\n  </Step>\n</Steps>\n\n---\n\n## Legal entity names on your statement\n\nDepending on the processor and region, your bank or credit-card statement will show one of these:\n\n| Processor / Region | Statement descriptor |\n|--------------------|----------------------|\n| **Stripe (global)** | `Emergent` or `Emergent Labs Inc.` |\n| **Razorpay (India)** | `AGIONE TECHNOLOGIES PRIVATE LIMITED` or `RAZORPAY*EMERGENT` |\n| **PagBrasil (Brazil)** | `PAGBRASIL*EMERGENT` |\n| **Paddle** | `PADDLE.NET*EMERGENT` (Paddle always processes USD) |\n| **RevenueCat** | `REVENUECAT*EMERGENT` (mobile IAP receipts) |\n\n<Note>\nThe India-region legal entity is **AGIONE TECHNOLOGIES PRIVATE LIMITED**; the US entity is **Emergent Labs Inc.** Statements may show \"Emergent\" or \"Agione\".\n</Note>\n\n<Note>\nPaddle acts as **merchant of record** and always processes payments in **USD**, handling applicable sales tax automatically.\n</Note>\n\n---\n\n## No stored cards\n\nEmergent **does not store** your card number, CVV, or full PAN. When you pay:\n\n1. The processor (Stripe, Razorpay, etc.) tokenizes your card and returns a non-sensitive token.\n2. We store only the token, last four digits, brand (Visa/Mastercard), and expiry, for display purposes.\n3. Subsequent purchases use the same token; you can manage saved methods in **Settings → Billing**.\n\n<Info>\nIf you delete a saved payment method, you will be prompted to re-enter card details on your next purchase. No billing happens without your explicit \"Buy\" click.\n</Info>\n\n---\n\n## Cryptocurrency & stablecoins\n\nWe accept **USDC** and **USDT** (per Stripe availability) through **Stripe crypto checkout**. When you select crypto:\n\n- You complete payment through Stripe's hosted crypto checkout flow.\n- Credits are added to your combined balance after payment confirmation.\n\n- The exchange rate is locked for a limited window; if your transaction is not confirmed in time, contact support at **support@emergent.sh** for manual reconciliation.\n\n<Warning title=\"Testnet tokens are not accepted\">\nOnly send mainnet stablecoins through the Stripe crypto checkout. Sending unsupported tokens or sending to the wrong address will result in **permanent loss**, we cannot recover cross-chain or misdirected sends.\n</Warning>\n\n<AccordionGroup>\n  <Accordion title=\"Can I pay in Bitcoin or Ethereum?\">\n    Not currently. We accept only **USDC** and **USDT** (per Stripe availability) via Stripe crypto checkout.\n  </Accordion>\n</AccordionGroup>\n\n---\n\n## Refunds\n\nEmergent's refund policy: **purchased top-up credits are non-refundable**. However, if you cancel a subscription, you may be eligible for a prorated dollar refund of unused subscription credits (published app usage is subtracted first). To request a refund, contact **support@emergent.sh** with your transaction details.\n\n<Note>\nOnly subscription credits are eligible for prorated refunds on cancellation. Top-up (manually purchased) credits are non-refundable under any circumstance.\n</Note>\n\n---\n\n## Billing entity & taxes\n\nEmergent is a B2C platform. **GST/VAT invoices are not issued, and invoices cannot be edited after issuance.** Tax included in pricing varies by region and processor:\n\n- **Paddle** (USD): Handles applicable sales tax as merchant of record.\n- **Razorpay** (India): Taxes may be included; no GST invoice is provided.\n- **PagBrasil** (Brazil): Local taxes included in the BRL-equivalent rate.\n- **Stripe (EU/UK)**: VAT may be applied at checkout depending on region.\n\nIf you have specific tax documentation requirements, contact **support@emergent.sh**.\n\n---\n\n## Changing your payment gateway\n\nTo change your payment gateway or preferred processor, contact **support@emergent.sh**. Gateway changes are not self-service.\n\n<Note>\nAll credits, regardless of the currency or processor used at purchase, are added to your **single combined balance**. There are no separate per-currency balances.\n</Note>\n\n---\n\n## Common issues\n\n<AccordionGroup>\n  <Accordion title=\"Payment succeeded but credits didn't arrive\">\n    Webhook delays can take up to 5 minutes. Check **Settings → Billing → Transaction History**. If the status is \"Pending,\" wait. If \"Failed,\" contact **support@emergent.sh** with your transaction ID.\n  </Accordion>\n  <Accordion title=\"Card declined, what should I do?\">\n    Common causes: insufficient funds, 3DS challenge not completed, card not enabled for international transactions, or anti-fraud block. Try a different card or payment method (UPI, bank transfer, crypto). Contact **support@emergent.sh** if the issue persists.\n  </Accordion>\n  <Accordion title=\"Can I use a prepaid or virtual card?\">\n    Yes, as long as the card supports merchant authorizations. Some virtual cards block tokenization, test with a small purchase first.\n  </Accordion>\n  <Accordion title=\"Do you support purchase orders or NET-30 invoicing?\">\n\n    Enterprise plan customers may have access to PO/NET-30 billing arrangements. Contact **support@emergent.sh** for details.\n  </Accordion>\n</AccordionGroup>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n  <Card title=\"How credits work\" icon=\"coins\" href=\"/managing-credit-usage\">\n    Understand credit consumption, metering, and rate limits.\n  </Card>\n  <Card title=\"Managing credit usage\" icon=\"clock\" href=\"/managing-credit-usage\">\n    Expiry rules, auto-recharge, and low-balance alerts.\n  </Card>\n</CardGroup>","published_title":"Payment methods & regional billing","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"aa98efd9-ab10-4de3-b862-1f28daabc4b8","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Cancellation & refunds","slug":"cancellation-refunds","content":"## Cancelling your subscription\n\nYou can cancel your Emergent subscription at any time through the web app, mobile app, or directly in the Stripe customer portal.\n\n<Steps>\n  <Step title=\"Cancel via web or mobile app\">\n    Navigate to **Settings** → **Billing** and select **Cancel subscription**. You'll be asked to confirm; once confirmed, your subscription moves to a cancelled state at the end of the current billing period.\n  </Step>\n  <Step title=\"Cancel via Stripe\">\n    If you subscribed through Stripe Checkout, you can also manage your subscription in the [Stripe customer portal](/stripe). Click **Manage billing in Settings → Billing to open the portal, then choose Cancel subscription**.\n  </Step>\n</Steps>\n\n<Note>\nCancellations take effect at the end of your current billing cycle. You retain full access and any remaining subscription credits until that date.\n</Note>\n\n## What happens to your credits\n\nWhen you cancel, the treatment of your credits depends on how you acquired them:\n\n| Credit type | What happens on cancellation |\n|-------------|------------------------------|\n| **Subscription credits** (monthly allowance) | Remain usable until the end of the current billing period, then expire. Any unused balance is forfeited. |\n| **Top-up credits** (one-time purchases) | Persist indefinitely. You can continue using them on the Free plan after your subscription ends. See [Managing credit usage](/managing-credit-usage) for details. |\n\n<Tip>\nIf you have unused top-up credits, consider downgrading to the Free plan instead of cancelling outright. You'll keep access to your apps and can spend those credits over time.\n</Tip>\n\n## What happens to your apps\n\nAll apps you've built remain **preserved and accessible** after cancellation; however, live published versions will stay up only while credits cover the tier fee. Without sufficient credits, published versions go offline. You can:\n\n- View, test and share live URLs (while credits cover the tier fee)\n- Export code or download assets\n- Re-run builds using top-up credits (if you have any) or by resubscribing\n\n<Warning title=\"New builds require credits\">\nOnce subscription credits expire, you'll need top-up credits or an active plan to create new apps or request changes to existing ones. Read-only access is always free.\n</Warning>\n\n## Refund eligibility\n\nEmergent offers **prorated refunds on subscription credits only**, subject to the conditions below.\n\n### Subscription credits (prorated)\n\nIf you cancel your subscription, you are eligible for a prorated dollar refund of unused subscription credits. To receive a refund, cancel your subscription first; published app usage will be subtracted from the refundable amount.\n\n<Steps>\n  <Step title=\"Request a refund\">\n    Email [support@emergent.sh](mailto:support@emergent.sh) with your account email and billing date. Include a brief reason (optional but helpful).\n  </Step>\n  <Step title=\"Review & approval\">\n    The support team verifies usage and eligibility, typically within 1-2 business days.\n  </Step>\n  <Step title=\"Refund issued\">\n    Approved refunds are processed to your original payment method within 5-10 business days.\n  </Step>\n</Steps>\n\n### Top-up credits (non-refundable)\n\nOne-time credit top-ups are **final and non-refundable** once purchased. Because top-up credits never expire and can be used at any time, they are treated as a stored balance rather than a subscription service.\n\n<Info>\nTop-up credits remain in your account even if you downgrade or cancel. You can always return and spend them later.\n</Info>\n\n## Disputes and chargebacks\n\nIf you file a chargeback or payment dispute with your bank or card issuer **before contacting support**, your account will be automatically suspended to prevent fraud. To resolve:\n\n1. **Contact support first** at [support@emergent.sh](mailto:support@emergent.sh). Most billing issues can be resolved quickly.\n2. If a chargeback has already been filed, email us immediately with details. We'll work with you and the payment processor to close the dispute and restore access.\n\n<Danger title=\"Chargeback consequences\">\nAccounts with unresolved chargebacks may be permanently closed and banned from future use of the platform.\n</Danger>\n\n## Retention offers\n\nIf you're cancelling due to cost, usage limits, or a missing feature, **let us know**. We occasionally offer:\n\n- **Discounted plans** for students, educators, or non-profits\n\n- **Extended trials** if you're evaluating the platform for a larger project\n- **Custom credit packages** for teams with specific usage patterns\n\nReach out to [support@emergent.sh](mailto:support@emergent.sh) before cancelling. We'll do our best to find a solution that works for you.\n\n---\n\nFor more on how credits are allocated and consumed, see [Managing credit usage](/managing-credit-usage). For billing management and invoices, see [Stripe](/stripe).","order":50,"parent_id":null,"icon":"tag","description":"How to cancel (web/mobile/Stripe), what happens to credits and apps after cancelling, refund eligibility (prorated subscription credits only; top-ups non-refundable), disputes/char","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:48.231493+00:00","published_at":"2026-09-22T06:20:48.231493+00:00","published_content":"## Cancelling your subscription\n\nYou can cancel your Emergent subscription at any time through the web app, mobile app, or directly in the Stripe customer portal.\n\n<Steps>\n  <Step title=\"Cancel via web or mobile app\">\n    Navigate to **Settings** → **Billing** and select **Cancel subscription**. You'll be asked to confirm; once confirmed, your subscription moves to a cancelled state at the end of the current billing period.\n  </Step>\n  <Step title=\"Cancel via Stripe\">\n    If you subscribed through Stripe Checkout, you can also manage your subscription in the [Stripe customer portal](/stripe). Click **Manage billing in Settings → Billing to open the portal, then choose Cancel subscription**.\n  </Step>\n</Steps>\n\n<Note>\nCancellations take effect at the end of your current billing cycle. You retain full access and any remaining subscription credits until that date.\n</Note>\n\n## What happens to your credits\n\nWhen you cancel, the treatment of your credits depends on how you acquired them:\n\n| Credit type | What happens on cancellation |\n|-------------|------------------------------|\n| **Subscription credits** (monthly allowance) | Remain usable until the end of the current billing period, then expire. Any unused balance is forfeited. |\n| **Top-up credits** (one-time purchases) | Persist indefinitely. You can continue using them on the Free plan after your subscription ends. See [Managing credit usage](/managing-credit-usage) for details. |\n\n<Tip>\nIf you have unused top-up credits, consider downgrading to the Free plan instead of cancelling outright. You'll keep access to your apps and can spend those credits over time.\n</Tip>\n\n## What happens to your apps\n\nAll apps you've built remain **preserved and accessible** after cancellation; however, live published versions will stay up only while credits cover the tier fee. Without sufficient credits, published versions go offline. You can:\n\n- View, test and share live URLs (while credits cover the tier fee)\n- Export code or download assets\n- Re-run builds using top-up credits (if you have any) or by resubscribing\n\n<Warning title=\"New builds require credits\">\nOnce subscription credits expire, you'll need top-up credits or an active plan to create new apps or request changes to existing ones. Read-only access is always free.\n</Warning>\n\n## Refund eligibility\n\nEmergent offers **prorated refunds on subscription credits only**, subject to the conditions below.\n\n### Subscription credits (prorated)\n\nIf you cancel your subscription, you are eligible for a prorated dollar refund of unused subscription credits. To receive a refund, cancel your subscription first; published app usage will be subtracted from the refundable amount.\n\n<Steps>\n  <Step title=\"Request a refund\">\n    Email [support@emergent.sh](mailto:support@emergent.sh) with your account email and billing date. Include a brief reason (optional but helpful).\n  </Step>\n  <Step title=\"Review & approval\">\n    The support team verifies usage and eligibility, typically within 1-2 business days.\n  </Step>\n  <Step title=\"Refund issued\">\n    Approved refunds are processed to your original payment method within 5-10 business days.\n  </Step>\n</Steps>\n\n### Top-up credits (non-refundable)\n\nOne-time credit top-ups are **final and non-refundable** once purchased. Because top-up credits never expire and can be used at any time, they are treated as a stored balance rather than a subscription service.\n\n<Info>\nTop-up credits remain in your account even if you downgrade or cancel. You can always return and spend them later.\n</Info>\n\n## Disputes and chargebacks\n\nIf you file a chargeback or payment dispute with your bank or card issuer **before contacting support**, your account will be automatically suspended to prevent fraud. To resolve:\n\n1. **Contact support first** at [support@emergent.sh](mailto:support@emergent.sh). Most billing issues can be resolved quickly.\n2. If a chargeback has already been filed, email us immediately with details. We'll work with you and the payment processor to close the dispute and restore access.\n\n<Danger title=\"Chargeback consequences\">\nAccounts with unresolved chargebacks may be permanently closed and banned from future use of the platform.\n</Danger>\n\n## Retention offers\n\nIf you're cancelling due to cost, usage limits, or a missing feature, **let us know**. We occasionally offer:\n\n- **Discounted plans** for students, educators, or non-profits\n\n- **Extended trials** if you're evaluating the platform for a larger project\n- **Custom credit packages** for teams with specific usage patterns\n\nReach out to [support@emergent.sh](mailto:support@emergent.sh) before cancelling. We'll do our best to find a solution that works for you.\n\n---\n\nFor more on how credits are allocated and consumed, see [Managing credit usage](/managing-credit-usage). For billing management and invoices, see [Stripe](/stripe).","published_title":"Cancellation & refunds","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"5601ad3c-5fe7-4965-921f-2513999071a0","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Custom agents","slug":"custom-agents","content":"## Agent architecture\n\nEmergent uses a **hierarchical agent system to break down complex application-building tasks into manageable units of work. At the top level, a main agent** orchestrates the overall build process, while **sub-agents** handle specialized tasks like testing, published app, or integration work.\n\nEach agent is a language model instance equipped with:\n\n- **Context** - the current state of your app (files, preview database schema, dependencies)\n- **Tools** - callable functions to read/write code, run commands, query the database, publish, etc.\n- **Instructions** - system prompts that define the agent's role and constraints\n- **Memory** - conversation history and state from prior turns\n\nAgents collaborate by spawning sub-agents when a task requires focused expertise (for example, a sub-agent might handle writing unit tests while the main agent continues with feature development). This division of labor keeps each agent's context window focused and improves both speed and quality.\n\n<Note>\nYou can inspect agent logs, tool calls, and sub-agent activity in real time as your app builds.\n</Note>\n\n---\n\n## Main agents\n\nThe **main agent** is the primary autonomous worker that interprets your chat messages and drives the build-test-publish cycle. When you describe a feature, fix, or new app in chat, the main agent:\n\n1. **Plans** the work by breaking your request into implementation steps\n2. **Executes** those steps using its tools (editing files, running commands, querying docs)\n3. **Validates** the result (spawning test sub-agents, checking build output)\n4. **Reports back** in chat with a summary, diff preview, or follow-up questions\n\nThe main agent has access to the full workspace: your app's source tree, environment variables, database, and publish config. It decides when to delegate work to sub-agents and when to proceed autonomously.\n\n**Stop reasons** determine when a main agent pauses and returns control to you. Common stop reasons include:\n\n- Successful completion of your request\n- A question or clarification needed\n- An error that requires human input (e.g., missing API key)\n- Credit budget exhausted\n\nFor a detailed walk-through of the agent workflow, see [How the agent runs](/how-the-agent-runs-workflow-stop-reasons).\n\n---\n\n## Sub-agents\n\n**Sub-agents** are ephemeral, specialized agents spawned by the main agent to handle discrete tasks. They inherit relevant context from the main agent but operate with a narrower scope and tailored instructions.\n\nCommon sub-agent roles:\n\n- **Test agents** - write and run unit/integration tests, validate outputs\n- **Published app agents** - handle build steps, environment provisioning, and publish commands\n- **Integration agents** - configure third-party services (Stripe, Twilio, MCP servers)\n- **Refactor agents** - clean up code, apply linting, optimize performance\n\nSub-agents execute in parallel when possible, report results back to the main agent, and terminate once their task completes. They do not persist across turns or interact directly with you in chat.\n\n<Tip>\nSub-agent logs appear nested under the main agent's activity. You can expand them to see tool calls and outputs.\n</Tip>\n\n---\n\n## Custom tools\n\nYou can extend agent capabilities by providing **custom tools** via MCP (Model Context Protocol) servers. Custom tools are useful for:\n\n- Calling proprietary or internal APIs not covered by built-in integrations\n- Performing domain-specific calculations or transformations\n- Interfacing with hardware, legacy systems, or non-standard data sources\n\n### Registering a custom tool (MCP server)\n\nCustom tools are **MCP servers** registered through the platform UI. There is no `tools/` directory, tools are not auto-discovered from files.\n\n<Steps>\n<Step title=\"Open Manage Agents\">\nGo to **Account Settings → Manage Agents → MCP tab**.\n</Step>\n\n<Step title=\"Configure the MCP server\">\nThe modal has separate **Name** and **Description** form fields (above the JSON box) - these are their own inputs, not JSON keys. Fill those in, then enter your MCP server configuration as JSON in the `mcpServers` format.\n\nEach server entry takes `command`, `args`, and `env` - this launches a local process (for example `npx`). There is no `url` field anywhere in this modal.\n\n```json\n{\n  \"mcpServers\": {\n    \"your-tool\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@your-org/mcp-server\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n</Step>\n\n<Step title=\"Verify and Save\">\nClick **Verify and Save** to validate the configuration and register the MCP server with your agents.\n</Step>\n\n<Step title=\"Inspect tool calls\">\nCheck the agent activity log to see arguments passed and results returned.\n</Step>\n</Steps>\n\n<Warning title=\"Tool execution security\">\nCustom tools run as MCP servers accessible to your agents. Avoid executing untrusted input or performing destructive operations without validation.\n</Warning>\n\n### Tool best practices\n\n- **Keep tools focused** - one tool per discrete operation. Agents compose multiple tool calls for complex workflows.\n- **Provide clear descriptions** - agents rely on natural-language descriptions to decide when to use a tool.\n- **Return structured data** - JSON objects are easier for agents to parse than free-form strings.\n- **Handle errors gracefully** - return `{ error: \"message\" }` rather than throwing, so agents can retry or adjust strategy.\n\nFor integrating external platforms via the Model Context Protocol (MCP), see [Custom & MCP integrations](/custom-mcp-integrations).","order":52,"parent_id":null,"icon":"robot","description":"Custom agents","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T10:20:37.822886+00:00","published_at":"2026-09-25T10:20:37.822886+00:00","published_content":"## Agent architecture\n\nEmergent uses a **hierarchical agent system to break down complex application-building tasks into manageable units of work. At the top level, a main agent** orchestrates the overall build process, while **sub-agents** handle specialized tasks like testing, published app, or integration work.\n\nEach agent is a language model instance equipped with:\n\n- **Context** - the current state of your app (files, preview database schema, dependencies)\n- **Tools** - callable functions to read/write code, run commands, query the database, publish, etc.\n- **Instructions** - system prompts that define the agent's role and constraints\n- **Memory** - conversation history and state from prior turns\n\nAgents collaborate by spawning sub-agents when a task requires focused expertise (for example, a sub-agent might handle writing unit tests while the main agent continues with feature development). This division of labor keeps each agent's context window focused and improves both speed and quality.\n\n<Note>\nYou can inspect agent logs, tool calls, and sub-agent activity in real time as your app builds.\n</Note>\n\n---\n\n## Main agents\n\nThe **main agent** is the primary autonomous worker that interprets your chat messages and drives the build-test-publish cycle. When you describe a feature, fix, or new app in chat, the main agent:\n\n1. **Plans** the work by breaking your request into implementation steps\n2. **Executes** those steps using its tools (editing files, running commands, querying docs)\n3. **Validates** the result (spawning test sub-agents, checking build output)\n4. **Reports back** in chat with a summary, diff preview, or follow-up questions\n\nThe main agent has access to the full workspace: your app's source tree, environment variables, database, and publish config. It decides when to delegate work to sub-agents and when to proceed autonomously.\n\n**Stop reasons** determine when a main agent pauses and returns control to you. Common stop reasons include:\n\n- Successful completion of your request\n- A question or clarification needed\n- An error that requires human input (e.g., missing API key)\n- Credit budget exhausted\n\nFor a detailed walk-through of the agent workflow, see [How the agent runs](/how-the-agent-runs-workflow-stop-reasons).\n\n---\n\n## Sub-agents\n\n**Sub-agents** are ephemeral, specialized agents spawned by the main agent to handle discrete tasks. They inherit relevant context from the main agent but operate with a narrower scope and tailored instructions.\n\nCommon sub-agent roles:\n\n- **Test agents** - write and run unit/integration tests, validate outputs\n- **Published app agents** - handle build steps, environment provisioning, and publish commands\n- **Integration agents** - configure third-party services (Stripe, Twilio, MCP servers)\n- **Refactor agents** - clean up code, apply linting, optimize performance\n\nSub-agents execute in parallel when possible, report results back to the main agent, and terminate once their task completes. They do not persist across turns or interact directly with you in chat.\n\n<Tip>\nSub-agent logs appear nested under the main agent's activity. You can expand them to see tool calls and outputs.\n</Tip>\n\n---\n\n## Custom tools\n\nYou can extend agent capabilities by providing **custom tools** via MCP (Model Context Protocol) servers. Custom tools are useful for:\n\n- Calling proprietary or internal APIs not covered by built-in integrations\n- Performing domain-specific calculations or transformations\n- Interfacing with hardware, legacy systems, or non-standard data sources\n\n### Registering a custom tool (MCP server)\n\nCustom tools are **MCP servers** registered through the platform UI. There is no `tools/` directory, tools are not auto-discovered from files.\n\n<Steps>\n<Step title=\"Open Manage Agents\">\nGo to **Account Settings → Manage Agents → MCP tab**.\n</Step>\n\n<Step title=\"Configure the MCP server\">\nThe modal has separate **Name** and **Description** form fields (above the JSON box) - these are their own inputs, not JSON keys. Fill those in, then enter your MCP server configuration as JSON in the `mcpServers` format.\n\nEach server entry takes `command`, `args`, and `env` - this launches a local process (for example `npx`). There is no `url` field anywhere in this modal.\n\n```json\n{\n  \"mcpServers\": {\n    \"your-tool\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@your-org/mcp-server\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n</Step>\n\n<Step title=\"Verify and Save\">\nClick **Verify and Save** to validate the configuration and register the MCP server with your agents.\n</Step>\n\n<Step title=\"Inspect tool calls\">\nCheck the agent activity log to see arguments passed and results returned.\n</Step>\n</Steps>\n\n<Warning title=\"Tool execution security\">\nCustom tools run as MCP servers accessible to your agents. Avoid executing untrusted input or performing destructive operations without validation.\n</Warning>\n\n### Tool best practices\n\n- **Keep tools focused** - one tool per discrete operation. Agents compose multiple tool calls for complex workflows.\n- **Provide clear descriptions** - agents rely on natural-language descriptions to decide when to use a tool.\n- **Return structured data** - JSON objects are easier for agents to parse than free-form strings.\n- **Handle errors gracefully** - return `{ error: \"message\" }` rather than throwing, so agents can retry or adjust strategy.\n\nFor integrating external platforms via the Model Context Protocol (MCP), see [Custom & MCP integrations](/custom-mcp-integrations).","published_title":"Custom agents","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"cf6e77fa-d133-44fb-afe5-004d0fafcfcb","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"How the agent runs (workflow & stop reasons)","slug":"how-the-agent-runs-workflow-stop-reasons","content":"## The Temporal workflow loop\n\nEvery agent conversation runs as a long-lived Temporal workflow. When you send a message, the workflow spins up (or resumes) and the agent enters an iterative loop:\n\n1. **Reason** - the LLM decides which tool to call next (or whether to reply to you).\n2. **Act** - execute the chosen tool (write code, run tests, search the web, etc.).\n3. **Observe** - collect the tool result and append it to the conversation context.\n4. **Repeat** - loop back to step 1 until a stop condition is met.\n\nThis architecture lets the agent chain dozens of actions autonomously - committing files, spinning up preview servers, invoking subagents - without requiring your approval at every step.\n\n<Info title=\"Temporal resilience\">\nBecause the workflow state persists in Temporal, the agent can survive transient infrastructure failures and resume exactly where it left off.\n</Info>\n\n## Stop reasons\n\nThe loop terminates when any of these conditions is true:\n\n| Stop reason | Meaning |\n|-------------|---------|\n| `context_overflow` | The conversation history exceeded the model's context window; the agent cannot fit the next turn. |\n| `max_iterations` | The agent hit the per-turn iteration cap (10,000 steps) to prevent runaway loops. |\n| `insufficient_credits` | Your account balance dropped below the cost of the next tool call. |\n| `end_turn` | The agent finished the task naturally. |\n| `handoff` | The agent handed control to another agent. |\n| `error` | An unrecoverable workflow error occurred (rare; usually retried automatically). |\n\nWhen the loop stops, you'll see a status indicator in the chat. An `end_turn` stop is normal and means the agent has completed your request. A `handoff` stop means the task has been passed to another agent. `context_overflow` or `max_iterations` usually signals the task grew too large for a single turn; break it into smaller requests or start a fresh conversation.\n\n<Warning title=\"Context overflow\">\nIf you hit `context_overflow` frequently, try asking the agent to summarize progress before starting a new subtask, or split the work across multiple chat threads.\n</Warning>\n\n## Iteration and time caps\n\nTo keep costs predictable and prevent infinite loops:\n\n- **Iteration cap**: 10,000 tool calls per user message (adjustable in the future for enterprise plans).\n- **Time cap**: workflows time out after 4 hours of wall-clock time, though most tasks complete in seconds to minutes.\n\nThe agent tracks its own loop count and will gracefully hand off as it approaches the iteration limit, summarizing what it accomplished and what remains.\n\n## Agent tools & their credit cost\n\nThe agent has access to a rich built-in toolset via the **sandbox MCP server**:\n\n- **File operations** - read, write, edit, list, move, delete files in your project.\n- **Shell execution** - run `npm`, `pnpm`, framework CLIs, git commands.\n- **Preview server** - spin up development servers and capture screenshots.\n- **Codex code review** - Codex reviews GitHub PRs via its workflow (linting, security scans, style checks).\n- **Testing agent** - writes and executes unit/integration/E2E tests in a separate subagent.\n- **Design agent** - generates UI mockups and design assets.\n\n<Info title=\"Free sandbox tools\">\nMost MCP sandbox tools (file I/O, shell, Codex) have **no additional credit cost** beyond the base LLM inference. You pay only for the model's input/output tokens.\n</Info>\n\nSome **server-side tools** do incur extra charges:\n\n- **Web search** - ~$0.01-0.014 per request (approximately 0.05-0.07 credits per query, varies by provider).\n\n- **Media generation** (images, videos) - cost depends on resolution and model; typically 5-20 credits per asset.\n\nWhen the agent calls one of these tools, the credit deduction happens immediately. If your balance is too low, the workflow stops with `insufficient_credits` and prompts you to [recharge](/managing-credit-usage).\n\n## E-1, E-2, and E-3 agents\n\nEmergent offers three distinct agents, selectable from the agent dropdown when creating a job:\n\n1. **E-1** - the default step-by-step builder; runs a structured, incremental workflow.\n2. **E-2** - an intermediate agent with a different workflow balance between autonomy and oversight.\n\n3. **E-3** - an opt-in autonomous agent that runs end-to-end, using E-1 as a sub-agent internally; only finishes or hands off when the task is complete.\n\n**E-1 is the default agent.** E-3 is opt-in for those who want fully autonomous runs. Agents cannot be switched mid-conversation (forking keeps the selected agent).\n\n<Tip>\nE-3 is ideal for iterative development (bug fixes, feature additions) where you want minimal interruptions. For major refactors or schema changes, E-1's step-by-step approach gives you more visibility.\n</Tip>\n\n## Subagents and specialization\n\nComplex tasks often spawn **subagents** - ephemeral worker agents with narrow mandates:\n\n- **Testing subagent** - writes test cases, runs them, reports coverage. Invoked via the `run_tests` tool.\n\n- **Design subagent** - generates wireframes, color palettes, component designs. Invoked via `generate_design`.\n- **Review subagent (Codex)** - performs linting, security scans, style checks. Codex reviews GitHub PRs via its workflow.\n\nSubagents run in parallel Temporal workflows and report results back to the parent agent. Their credit usage rolls up into your main conversation's total. This division of labor keeps context focused: the main agent handles orchestration, subagents handle depth.\n\n## Auto-HITL (human-in-the-loop)\n\nIn autonomous runs, when the agent encounters a question it needs answered, **Auto-HITL automatically generates the answer** so the workflow is not blocked. This means autonomous runs can continue without pausing for your input on routine clarifications.\n\nAuto-HITL engages when:\n\n- It encounters an ambiguous requirement (\"Should the button be primary or secondary?\").\n- A tool fails multiple times and the agent can't auto-recover.\n- The task requires a decision outside its training scope (legal compliance, branding choices).\n\nIn autonomous runs, Auto-HITL auto-answers the agent's ask_human (assuming a sensible default and continuing) so the run is never blocked; it does not pause for the user.\n\n<Note>\nAuto-HITL keeps autonomous runs unblocked by auto-answering the agent's questions. The iteration and time caps continue running during autonomous operation.\n</Note>\n\n## Monitoring workflow health\n\nThe workspace UI displays:\n\n- **Current step count** - how many iterations the agent has consumed this turn.\n- **Estimated credits remaining** - live balance update as tools execute.\n- **Subagent activity** - spinner badges when parallel workers are running.\n\nIf a workflow stalls or you suspect an infinite loop, you can **cancel** it from the chat overflow menu. The agent will gracefully shut down and hand off with a summary of partial progress.\n\nFor a deeper explore workspace controls, see [A tour of the workspace](/a-tour-of-the-workspace).","order":53,"parent_id":null,"icon":"robot","description":"The agent Temporal workflow loop, iteration/time caps, and stop reasons (context_overflow, max_iterations, insufficient_credits, handoff, etc.); E-3 autonomous phases, subagents an","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:20:51.176040+00:00","published_at":"2026-09-22T06:20:51.176040+00:00","published_content":"## The Temporal workflow loop\n\nEvery agent conversation runs as a long-lived Temporal workflow. When you send a message, the workflow spins up (or resumes) and the agent enters an iterative loop:\n\n1. **Reason** - the LLM decides which tool to call next (or whether to reply to you).\n2. **Act** - execute the chosen tool (write code, run tests, search the web, etc.).\n3. **Observe** - collect the tool result and append it to the conversation context.\n4. **Repeat** - loop back to step 1 until a stop condition is met.\n\nThis architecture lets the agent chain dozens of actions autonomously - committing files, spinning up preview servers, invoking subagents - without requiring your approval at every step.\n\n<Info title=\"Temporal resilience\">\nBecause the workflow state persists in Temporal, the agent can survive transient infrastructure failures and resume exactly where it left off.\n</Info>\n\n## Stop reasons\n\nThe loop terminates when any of these conditions is true:\n\n| Stop reason | Meaning |\n|-------------|---------|\n| `context_overflow` | The conversation history exceeded the model's context window; the agent cannot fit the next turn. |\n| `max_iterations` | The agent hit the per-turn iteration cap (10,000 steps) to prevent runaway loops. |\n| `insufficient_credits` | Your account balance dropped below the cost of the next tool call. |\n| `end_turn` | The agent finished the task naturally. |\n| `handoff` | The agent handed control to another agent. |\n| `error` | An unrecoverable workflow error occurred (rare; usually retried automatically). |\n\nWhen the loop stops, you'll see a status indicator in the chat. An `end_turn` stop is normal and means the agent has completed your request. A `handoff` stop means the task has been passed to another agent. `context_overflow` or `max_iterations` usually signals the task grew too large for a single turn; break it into smaller requests or start a fresh conversation.\n\n<Warning title=\"Context overflow\">\nIf you hit `context_overflow` frequently, try asking the agent to summarize progress before starting a new subtask, or split the work across multiple chat threads.\n</Warning>\n\n## Iteration and time caps\n\nTo keep costs predictable and prevent infinite loops:\n\n- **Iteration cap**: 10,000 tool calls per user message (adjustable in the future for enterprise plans).\n- **Time cap**: workflows time out after 4 hours of wall-clock time, though most tasks complete in seconds to minutes.\n\nThe agent tracks its own loop count and will gracefully hand off as it approaches the iteration limit, summarizing what it accomplished and what remains.\n\n## Agent tools & their credit cost\n\nThe agent has access to a rich built-in toolset via the **sandbox MCP server**:\n\n- **File operations** - read, write, edit, list, move, delete files in your project.\n- **Shell execution** - run `npm`, `pnpm`, framework CLIs, git commands.\n- **Preview server** - spin up development servers and capture screenshots.\n- **Codex code review** - Codex reviews GitHub PRs via its workflow (linting, security scans, style checks).\n- **Testing agent** - writes and executes unit/integration/E2E tests in a separate subagent.\n- **Design agent** - generates UI mockups and design assets.\n\n<Info title=\"Free sandbox tools\">\nMost MCP sandbox tools (file I/O, shell, Codex) have **no additional credit cost** beyond the base LLM inference. You pay only for the model's input/output tokens.\n</Info>\n\nSome **server-side tools** do incur extra charges:\n\n- **Web search** - ~$0.01-0.014 per request (approximately 0.05-0.07 credits per query, varies by provider).\n\n- **Media generation** (images, videos) - cost depends on resolution and model; typically 5-20 credits per asset.\n\nWhen the agent calls one of these tools, the credit deduction happens immediately. If your balance is too low, the workflow stops with `insufficient_credits` and prompts you to [recharge](/managing-credit-usage).\n\n## E-1, E-2, and E-3 agents\n\nEmergent offers three distinct agents, selectable from the agent dropdown when creating a job:\n\n1. **E-1** - the default step-by-step builder; runs a structured, incremental workflow.\n2. **E-2** - an intermediate agent with a different workflow balance between autonomy and oversight.\n\n3. **E-3** - an opt-in autonomous agent that runs end-to-end, using E-1 as a sub-agent internally; only finishes or hands off when the task is complete.\n\n**E-1 is the default agent.** E-3 is opt-in for those who want fully autonomous runs. Agents cannot be switched mid-conversation (forking keeps the selected agent).\n\n<Tip>\nE-3 is ideal for iterative development (bug fixes, feature additions) where you want minimal interruptions. For major refactors or schema changes, E-1's step-by-step approach gives you more visibility.\n</Tip>\n\n## Subagents and specialization\n\nComplex tasks often spawn **subagents** - ephemeral worker agents with narrow mandates:\n\n- **Testing subagent** - writes test cases, runs them, reports coverage. Invoked via the `run_tests` tool.\n\n- **Design subagent** - generates wireframes, color palettes, component designs. Invoked via `generate_design`.\n- **Review subagent (Codex)** - performs linting, security scans, style checks. Codex reviews GitHub PRs via its workflow.\n\nSubagents run in parallel Temporal workflows and report results back to the parent agent. Their credit usage rolls up into your main conversation's total. This division of labor keeps context focused: the main agent handles orchestration, subagents handle depth.\n\n## Auto-HITL (human-in-the-loop)\n\nIn autonomous runs, when the agent encounters a question it needs answered, **Auto-HITL automatically generates the answer** so the workflow is not blocked. This means autonomous runs can continue without pausing for your input on routine clarifications.\n\nAuto-HITL engages when:\n\n- It encounters an ambiguous requirement (\"Should the button be primary or secondary?\").\n- A tool fails multiple times and the agent can't auto-recover.\n- The task requires a decision outside its training scope (legal compliance, branding choices).\n\nIn autonomous runs, Auto-HITL auto-answers the agent's ask_human (assuming a sensible default and continuing) so the run is never blocked; it does not pause for the user.\n\n<Note>\nAuto-HITL keeps autonomous runs unblocked by auto-answering the agent's questions. The iteration and time caps continue running during autonomous operation.\n</Note>\n\n## Monitoring workflow health\n\nThe workspace UI displays:\n\n- **Current step count** - how many iterations the agent has consumed this turn.\n- **Estimated credits remaining** - live balance update as tools execute.\n- **Subagent activity** - spinner badges when parallel workers are running.\n\nIf a workflow stalls or you suspect an infinite loop, you can **cancel** it from the chat overflow menu. The agent will gracefully shut down and hand off with a summary of partial progress.\n\nFor a deeper explore workspace controls, see [A tour of the workspace](/a-tour-of-the-workspace).","published_title":"How the agent runs (workflow & stop reasons)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"831ab708-957f-4aa6-b4af-ec5a151c05b6","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"What and How","slug":"what-and-how","content":"## What integrations are\n\nAn **integration** in Emergent is any connection between your app and a third-party service - a database, an authentication provider, a payment processor, an email API, a vector store, or an external API.\n\nWhen you describe your app in chat, the agent decides which integrations are needed and configures them automatically. You don't manually wire up connection strings, OAuth flows, or SDK clients; the agent does that for you as part of the build.\n\nCommon examples:\n\n- **Storage** : Emergent Managed File and object storage\n- **Auth**: [Emergent Auth](/emergent-auth-built-in)\n- **Payments**: Stripe , Razorpay , Paypal, Paystack\n- **Communications**: Resend, SendGrid,Twilio\n- **AI**: OpenAI, Anthropic, Gemini, ElevenLabs,Perplexity\n- **Other APIs**: any REST or GraphQL endpoint your app needs\n\nBrowse the full set in the [Key integrations catalogue](/key-integrations-catalogue).\n\n---\n\n## How auth & keys are handled\n\nEmergent takes care of the plumbing so you can focus on describing _what_ your app should do, not _how_ to wire it up.\n\n### What Emergent does for you\n\n<Steps>\n<Step title=\"Detects the integration\">\nWhen you mention a feature - \"users sign in with Google\" or \"users can use Stripe to checkout\" - the agent identifies the service and adds the integration to your app.\n</Step>\n\n<Step title=\"Builds the connection framework\">\nThe agent installs the necessary SDK, injects environment variables, and writes the glue code (init clients, handle callbacks, manage sessions).\n</Step>\n\n<Step title=\"Prompts for keys when needed\">\nIf a service requires an API key or secret, Emergent prompts you to provide it. You paste the key into the workspace UI; it's stored encrypted and injected at runtime.\n</Step>\n</Steps>\n\n<Note>\nAPI keys and secrets you supply are encrypted at rest and never shared. Only your app's runtime environment can decrypt them.\n</Note>\n\n### What you supply\n\nFor most third-party services, **you bring your own account and API key**:\n\n- Sign up with the service (Stripe, OpenAI etc.)\n- Generate an API key or secret in their dashboard\n- Paste it into Emergent when prompted\n\nThe agent will tell you exactly which key it needs and where to find it.\n\n<Tip>\nSome integrations (like [Emergent Auth](/emergent-auth-built-in)) are fully managed - no external account or key required.\n</Tip>\n\n---\n\n## When keys are requested\n\nYou'll be asked to provide a key in two situations:\n\n1. **During the build**: The agent pauses and prompts you in chat. Paste the key, then resume.\n\n2. **After publish**: If a key is missing or invalid, the app will fail at runtime. Check the logs, ask the agent to add the missing key to `.env` and republish (the Secrets UI can only edit values of existing keys, it cannot add new ones).\n\n<Warning>\nIf you skip providing a required key, the agent may stub out the integration or the feature will break at runtime. Always supply keys when prompted.\n</Warning>\n\n---\n\n## Environment variables & secrets\n\nUnder the hood, every integration key becomes an **environment variable** (e.g. `OPENAI_API_KEY`, `STRIPE_SECRET_KEY`). The agent:\n\n- Declares the variable in your app's config\n- Injects it at build and runtime\n- Uses it in the code (e.g. `process.env.OPENAI_API_KEY`)\n\nYou can view and edit these variables in the workspace **Settings** panel. See [A tour of the workspace](/a-tour-of-the-workspace) for details.\n\n---\n\n## Next steps\n\n<CardGroup cols={2}>\n<Card title=\"Key integrations catalogue\" href=\"/key-integrations-catalogue\">\nBrowse supported services and their setup requirements\n</Card>\n<Card title=\"Emergent Auth\" href=\"/emergent-auth-built-in\">\nUse the platform's managed auth - no external account needed\n</Card>\n<Card title=\"Your data & ownership\" href=\"/your-data-ownership\">\nUnderstand how your keys, data and code are stored and protected\n</Card>\n</CardGroup>","order":54,"parent_id":null,"icon":"file-text","description":"1. What integrations are: how Emergent connects your app to third-party services.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.734403+00:00","published_at":"2026-09-22T06:19:16.734403+00:00","published_content":"## What integrations are\n\nAn **integration** in Emergent is any connection between your app and a third-party service - a database, an authentication provider, a payment processor, an email API, a vector store, or an external API.\n\nWhen you describe your app in chat, the agent decides which integrations are needed and configures them automatically. You don't manually wire up connection strings, OAuth flows, or SDK clients; the agent does that for you as part of the build.\n\nCommon examples:\n\n- **Storage** : Emergent Managed File and object storage\n- **Auth**: [Emergent Auth](/emergent-auth-built-in)\n- **Payments**: Stripe , Razorpay , Paypal, Paystack\n- **Communications**: Resend, SendGrid,Twilio\n- **AI**: OpenAI, Anthropic, Gemini, ElevenLabs,Perplexity\n- **Other APIs**: any REST or GraphQL endpoint your app needs\n\nBrowse the full set in the [Key integrations catalogue](/key-integrations-catalogue).\n\n---\n\n## How auth & keys are handled\n\nEmergent takes care of the plumbing so you can focus on describing _what_ your app should do, not _how_ to wire it up.\n\n### What Emergent does for you\n\n<Steps>\n<Step title=\"Detects the integration\">\nWhen you mention a feature - \"users sign in with Google\" or \"users can use Stripe to checkout\" - the agent identifies the service and adds the integration to your app.\n</Step>\n\n<Step title=\"Builds the connection framework\">\nThe agent installs the necessary SDK, injects environment variables, and writes the glue code (init clients, handle callbacks, manage sessions).\n</Step>\n\n<Step title=\"Prompts for keys when needed\">\nIf a service requires an API key or secret, Emergent prompts you to provide it. You paste the key into the workspace UI; it's stored encrypted and injected at runtime.\n</Step>\n</Steps>\n\n<Note>\nAPI keys and secrets you supply are encrypted at rest and never shared. Only your app's runtime environment can decrypt them.\n</Note>\n\n### What you supply\n\nFor most third-party services, **you bring your own account and API key**:\n\n- Sign up with the service (Stripe, OpenAI etc.)\n- Generate an API key or secret in their dashboard\n- Paste it into Emergent when prompted\n\nThe agent will tell you exactly which key it needs and where to find it.\n\n<Tip>\nSome integrations (like [Emergent Auth](/emergent-auth-built-in)) are fully managed - no external account or key required.\n</Tip>\n\n---\n\n## When keys are requested\n\nYou'll be asked to provide a key in two situations:\n\n1. **During the build**: The agent pauses and prompts you in chat. Paste the key, then resume.\n\n2. **After publish**: If a key is missing or invalid, the app will fail at runtime. Check the logs, ask the agent to add the missing key to `.env` and republish (the Secrets UI can only edit values of existing keys, it cannot add new ones).\n\n<Warning>\nIf you skip providing a required key, the agent may stub out the integration or the feature will break at runtime. Always supply keys when prompted.\n</Warning>\n\n---\n\n## Environment variables & secrets\n\nUnder the hood, every integration key becomes an **environment variable** (e.g. `OPENAI_API_KEY`, `STRIPE_SECRET_KEY`). The agent:\n\n- Declares the variable in your app's config\n- Injects it at build and runtime\n- Uses it in the code (e.g. `process.env.OPENAI_API_KEY`)\n\nYou can view and edit these variables in the workspace **Settings** panel. See [A tour of the workspace](/a-tour-of-the-workspace) for details.\n\n---\n\n## Next steps\n\n<CardGroup cols={2}>\n<Card title=\"Key integrations catalogue\" href=\"/key-integrations-catalogue\">\nBrowse supported services and their setup requirements\n</Card>\n<Card title=\"Emergent Auth\" href=\"/emergent-auth-built-in\">\nUse the platform's managed auth - no external account needed\n</Card>\n<Card title=\"Your data & ownership\" href=\"/your-data-ownership\">\nUnderstand how your keys, data and code are stored and protected\n</Card>\n</CardGroup>","published_title":"What and How","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"104bce43-afeb-4401-a10f-83490ff056c5","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"MCPs & connectors","slug":"mcps-connectors","content":"## What is MCP?\n\nThe **Model Context Protocol** (MCP) is an open standard that lets AI agents discover and use external tools, data sources, and services. Instead of hard-coding integrations, agents speak MCP to dynamically fetch schemas, call functions, and retrieve context from any MCP-compatible server.\n\nIn Emergent, the build agent uses MCP connectors to pull real-time data (APIs, databases, file systems) and invoke external actions during code generation, testing, and published app.\n\n<Note>\nMCP servers expose **tools** (callable functions), **resources** (readable data), and **prompts** (reusable templates). Emergent's agent discovers these capabilities automatically when you register a server.\n</Note>\n\n## Using an MCP connector\n\nAn **MCP connector** bridges Emergent's build agent to an external service. When you register a connector, the agent can:\n\n- **Read resources** - fetch schemas, documentation, or live data (e.g., rows from a Notion database, files from Google Drive).\n- **Call tools** - trigger actions like sending a Slack message, creating a Jira ticket, or querying a REST API.\n- **Inject context** - use prompts defined by the server to guide code generation.\n\nCommon use cases:\n\n| Connector type | Example | What it enables |\n|----------------|---------|-----------------|\n| Database | PostgreSQL MCP | Read schemas, run queries, validate migrations |\n| SaaS API | Stripe MCP | Fetch product catalog, create checkout sessions |\n| File system | Local filesystem MCP | Access project templates, reference documents |\n| Communication | Slack MCP | Send notifications, read channel history |\n\n<Tip>\nThird-party MCP servers are often published as npm packages or Docker images. Check [modelcontextprotocol.io](https://modelcontextprotocol.io) or GitHub for community-maintained servers.\n</Tip>\n\n## Emergent as an MCP server\n\nEmergent itself exposes an **MCP interface** on port `8013` (local) or via a public endpoint when published. This lets you use Emergent as a tool from other AI clients - Claude Desktop, Cursor, or custom agents.\n\n**Available tools** (example):\n\n- `emergent.create_app` - start a new app from a prompt.\n- `emergent.deploy` - trigger published app of a workspace.\n- `emergent.get_logs` - retrieve build or runtime logs.\n\nTo connect from Claude Desktop or another MCP client, configure the server URL and any required API key in the client's MCP settings. Emergent will return its tool schemas, and the client can invoke them like any other MCP tool.\n\n<Info>\nSelf-hosting users can customize the exposed tools by editing the MCP server configuration in `config/mcp.json` (see installation docs for details).\n</Info>\n\n## Registering a custom MCP server\n\nTo give the build agent access to a custom or third-party MCP server:\n\n<Steps>\n<Step title=\"Prepare the server endpoint\">\nYour MCP server must listen on a reachable address (localhost for local dev, or a public HTTPS URL for cloud). Ensure it implements the MCP specification (`initialize`, `tools/list`, `tools/call`, etc.).\n</Step>\n\n<Step title=\"Add the server to your workspace config\">\nIn the Emergent workspace, open **Account Settings → Manage Agents → MCP tab** and add the server using the JSON `mcpServers` config. Provide:\n\n- **Name** - a unique identifier (e.g., `my-postgres-db`).\n- **Endpoint** - the base URL or `stdio` command (e.g., `http://localhost:8012` or `npx -y @modelcontextprotocol/server-postgres`).\n- **Auth** (if required) - API key, bearer token, or environment variable reference.\n- **Visibility** - `private` (workspace-only). Note: public MCP servers are admin-created only and cannot be set by individual users.\n</Step>\n\n<Step title=\"Save and test connection\">\nClick **Verify and Save**. Emergent will call the server's `initialize` method and cache the list of tools and resources. Check the Connection Status indicator - green means the agent can reach the server.\n</Step>\n\n<Step title=\"Use discovered tools in chat\">\nRegistered tools appear in the agent's tool palette. When you describe a task that matches a tool's schema, the agent will propose calling it. You can also reference the server explicitly:\n\n> \"Use the `my-postgres-db` connector to read the users table schema and generate a GraphQL API.\"\n\n</Step>\n</Steps>\n\n<Warning>\n**Port 8012** is the default for stdio-launched MCP servers in Emergent's local environment. If your server binds to a different port, specify the full URL in the endpoint field.\n</Warning>\n\n### Public vs. private servers\n\n- **Private** - only the current workspace can use this server. Config stored in workspace metadata.\n- **Public** - available across the platform; public MCP servers are admin-created only and cannot be configured by individual users.\n\nUse private for project-specific databases or credentials; use public for shared services (company Slack, internal APIs).\n\n### Tool discovery and caching\n\nEmergent caches tool schemas for **5 minutes** after the first successful connection. If you update the server's tools (add a new function, change parameters), wait for the cache to expire or start a new job to ensure the agent sees the latest tool list.\n\n<Tip>\nFor rapidly evolving servers, enable **Auto-refresh on job start** in the server settings. The agent will re-discover tools at the beginning of each build job, ensuring it always sees the latest API.\n</Tip>\n\n---\n\n**Next steps**\n\n<CardGroup cols={2}>\n<Card title=\"Explore connectors\" icon=\"plug\" href=\"/integrations/connectors\">\nBrowse pre-built connectors for popular services (databases, SaaS, cloud storage).\n</Card>\n<Card title=\"Custom agents\" icon=\"robot\" href=\"/custom-agents\">\nLearn how to extend the build agent with custom prompts and tool chains.\n</Card>\n</CardGroup>","order":55,"parent_id":null,"icon":"puzzle","description":"1. What MCP is: Model Context Protocol basics.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.877949+00:00","published_at":"2026-09-22T06:19:16.877949+00:00","published_content":"## What is MCP?\n\nThe **Model Context Protocol** (MCP) is an open standard that lets AI agents discover and use external tools, data sources, and services. Instead of hard-coding integrations, agents speak MCP to dynamically fetch schemas, call functions, and retrieve context from any MCP-compatible server.\n\nIn Emergent, the build agent uses MCP connectors to pull real-time data (APIs, databases, file systems) and invoke external actions during code generation, testing, and published app.\n\n<Note>\nMCP servers expose **tools** (callable functions), **resources** (readable data), and **prompts** (reusable templates). Emergent's agent discovers these capabilities automatically when you register a server.\n</Note>\n\n## Using an MCP connector\n\nAn **MCP connector** bridges Emergent's build agent to an external service. When you register a connector, the agent can:\n\n- **Read resources** - fetch schemas, documentation, or live data (e.g., rows from a Notion database, files from Google Drive).\n- **Call tools** - trigger actions like sending a Slack message, creating a Jira ticket, or querying a REST API.\n- **Inject context** - use prompts defined by the server to guide code generation.\n\nCommon use cases:\n\n| Connector type | Example | What it enables |\n|----------------|---------|-----------------|\n| Database | PostgreSQL MCP | Read schemas, run queries, validate migrations |\n| SaaS API | Stripe MCP | Fetch product catalog, create checkout sessions |\n| File system | Local filesystem MCP | Access project templates, reference documents |\n| Communication | Slack MCP | Send notifications, read channel history |\n\n<Tip>\nThird-party MCP servers are often published as npm packages or Docker images. Check [modelcontextprotocol.io](https://modelcontextprotocol.io) or GitHub for community-maintained servers.\n</Tip>\n\n## Emergent as an MCP server\n\nEmergent itself exposes an **MCP interface** on port `8013` (local) or via a public endpoint when published. This lets you use Emergent as a tool from other AI clients - Claude Desktop, Cursor, or custom agents.\n\n**Available tools** (example):\n\n- `emergent.create_app` - start a new app from a prompt.\n- `emergent.deploy` - trigger published app of a workspace.\n- `emergent.get_logs` - retrieve build or runtime logs.\n\nTo connect from Claude Desktop or another MCP client, configure the server URL and any required API key in the client's MCP settings. Emergent will return its tool schemas, and the client can invoke them like any other MCP tool.\n\n<Info>\nSelf-hosting users can customize the exposed tools by editing the MCP server configuration in `config/mcp.json` (see installation docs for details).\n</Info>\n\n## Registering a custom MCP server\n\nTo give the build agent access to a custom or third-party MCP server:\n\n<Steps>\n<Step title=\"Prepare the server endpoint\">\nYour MCP server must listen on a reachable address (localhost for local dev, or a public HTTPS URL for cloud). Ensure it implements the MCP specification (`initialize`, `tools/list`, `tools/call`, etc.).\n</Step>\n\n<Step title=\"Add the server to your workspace config\">\nIn the Emergent workspace, open **Account Settings → Manage Agents → MCP tab** and add the server using the JSON `mcpServers` config. Provide:\n\n- **Name** - a unique identifier (e.g., `my-postgres-db`).\n- **Endpoint** - the base URL or `stdio` command (e.g., `http://localhost:8012` or `npx -y @modelcontextprotocol/server-postgres`).\n- **Auth** (if required) - API key, bearer token, or environment variable reference.\n- **Visibility** - `private` (workspace-only). Note: public MCP servers are admin-created only and cannot be set by individual users.\n</Step>\n\n<Step title=\"Save and test connection\">\nClick **Verify and Save**. Emergent will call the server's `initialize` method and cache the list of tools and resources. Check the Connection Status indicator - green means the agent can reach the server.\n</Step>\n\n<Step title=\"Use discovered tools in chat\">\nRegistered tools appear in the agent's tool palette. When you describe a task that matches a tool's schema, the agent will propose calling it. You can also reference the server explicitly:\n\n> \"Use the `my-postgres-db` connector to read the users table schema and generate a GraphQL API.\"\n\n</Step>\n</Steps>\n\n<Warning>\n**Port 8012** is the default for stdio-launched MCP servers in Emergent's local environment. If your server binds to a different port, specify the full URL in the endpoint field.\n</Warning>\n\n### Public vs. private servers\n\n- **Private** - only the current workspace can use this server. Config stored in workspace metadata.\n- **Public** - available across the platform; public MCP servers are admin-created only and cannot be configured by individual users.\n\nUse private for project-specific databases or credentials; use public for shared services (company Slack, internal APIs).\n\n### Tool discovery and caching\n\nEmergent caches tool schemas for **5 minutes** after the first successful connection. If you update the server's tools (add a new function, change parameters), wait for the cache to expire or start a new job to ensure the agent sees the latest tool list.\n\n<Tip>\nFor rapidly evolving servers, enable **Auto-refresh on job start** in the server settings. The agent will re-discover tools at the beginning of each build job, ensuring it always sees the latest API.\n</Tip>\n\n---\n\n**Next steps**\n\n<CardGroup cols={2}>\n<Card title=\"Explore connectors\" icon=\"plug\" href=\"/integrations/connectors\">\nBrowse pre-built connectors for popular services (databases, SaaS, cloud storage).\n</Card>\n<Card title=\"Custom agents\" icon=\"robot\" href=\"/custom-agents\">\nLearn how to extend the build agent with custom prompts and tool chains.\n</Card>\n</CardGroup>","published_title":"MCPs & connectors","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"1badcbfe-0a45-4279-9689-4a3f31d67512","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Key integrations catalogue","slug":"key-integrations-catalogue","content":"## Overview\n\nEmergent supports a curated set of integrations that let your app connect to third-party APIs, databases, and services without leaving the platform. Each integration is configured through **Preview → Manage → Integrations**, or by asking the agent, and the platform securely injects credentials at runtime.\n\n<Info>\nAll API keys and secrets are encrypted at rest and never exposed in logs or client-side code.\n</Info>\n\n---\n\n## AI\n\n<CardGroup cols={2}>\n<Card title=\"Universal LLM Key\">\n    Access OpenAI, Anthropic, Google and other LLM providers through a single unified key managed by Emergent.\n</Card>\n<Card title=\"OpenAI\">\n    Direct integration for GPT models, embeddings, and assistants. Set `OPENAI_API_KEY` in your environment.\n</Card>\n<Card title=\"Anthropic\">\n    Claude models for chat and function calling. Requires `ANTHROPIC_API_KEY`.\n</Card>\n<Card title=\"Google AI\">\n    Vertex AI/Gemini models. Configure `GOOGLE_AI_API_KEY`.\n</Card>\n</CardGroup>\n\n---\n\n## Databases & Storage\n\n<CardGroup cols={2}>\n<Card title=\"Emergent Storage\">\n    Built-in file & media storage for uploads (images, videos, files), no external account needed.\n</Card>\n</CardGroup>\n\n---\n\n## Payment & Commerce\n\n<CardGroup cols={2}>\n<Card title=\"Stripe\">\n    Accept payments, manage subscriptions, and handle billing. Set `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY`.\n</Card>\n<Card title=\"PayPal\">\n    Alternative payment gateway. Configure `PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET`.\n</Card>\n<Card title=\"Shopify\">\n    E-commerce store integration. Requires `SHOPIFY_STORE_URL` and `SHOPIFY_ACCESS_TOKEN`.\n</Card>\n<Card title=\"Razorpay\">\n    Accept payments in India, UPI, cards, netbanking and wallets. Ask the agent to add Razorpay, then set your keys in the Secrets tab (click **Preview**, then **Manage**).\n</Card>\n<Card title=\"Paystack\">\n    Accept payments across African markets, cards, bank transfer, mobile money and more. Ask the agent to add Paystack, then set your keys in the Secrets tab (click **Preview**, then **Manage**).\n</Card>\n</CardGroup>\n\n---\n\n## Communication & Messaging\n\n<CardGroup cols={2}>\n<Card title=\"SendGrid\">\n    Transactional email delivery. Set `SENDGRID_API_KEY`.\n</Card>\n<Card title=\"Twilio\">\n    SMS, voice, and WhatsApp messaging. Requires `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`.\n</Card>\n<Card title=\"Resend\">\n    Send emails from your app. Emergent-managed - add it from the Integrations panel (Preview → Manage), no API key needed. Full-stack web apps only (not available on mobile/Expo projects).\n</Card>\n</CardGroup>\n\n---\n\n## Authentication & Identity\n\n<CardGroup cols={2}>\n<Card title=\"Emergent Auth\">\n    Built-in sign-in, email & password and Google, with no API keys to configure.\n</Card>\n</CardGroup>\n\n---\n\n## How to add an integration\n\n<Steps>\n<Step title=\"Open integrations\">\n    Navigate to **Preview → Manage → Integrations** in your workspace, or ask the agent to add the integration for you.\n</Step>\n  \n<Step title=\"Provide the required keys\">\n    The agent will ask you for the required integration keys and secret values, then securely add and wire them into the integration automatically.\n</Step>\n  \n<Step title=\"Re-publish\">\n    Re-publish your app to apply the integration and environment changes.\n</Step>\n</Steps>\n\n<Warning>\nNever commit API keys to your repository or share them in chat. Always use environment variables.\n</Warning>\n\n---\n\n## Request a new integration\n\nIf you need an integration not listed here, describe it in chat and the AI agents will attempt to configure it using standard REST APIs or SDKs. For official platform support, contact the Emergent team or submit a feature request.\n\n<Tip>\nMost modern APIs work out-of-the-box by setting the appropriate environment variables and installing the vendor's SDK through chat (e.g., \"install the Notion SDK and connect to my workspace\").\n</Tip>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Integrations & scheduled tasks\" href=\"/integrations-scheduled-tasks\">\n    Learn how integrations work and how to set up recurring jobs.\n</Card>\n<Card title=\"A tour of the workspace\" href=\"/a-tour-of-the-workspace\">\n    Overview of the workspace UI and where to manage environment variables.\n</Card>\n</CardGroup>","order":56,"parent_id":null,"icon":"puzzle","description":"Directory of supported integrations, grouped by category.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.738648+00:00","published_at":"2026-09-22T06:19:16.738648+00:00","published_content":"## Overview\n\nEmergent supports a curated set of integrations that let your app connect to third-party APIs, databases, and services without leaving the platform. Each integration is configured through **Preview → Manage → Integrations**, or by asking the agent, and the platform securely injects credentials at runtime.\n\n<Info>\nAll API keys and secrets are encrypted at rest and never exposed in logs or client-side code.\n</Info>\n\n---\n\n## AI\n\n<CardGroup cols={2}>\n<Card title=\"Universal LLM Key\">\n    Access OpenAI, Anthropic, Google and other LLM providers through a single unified key managed by Emergent.\n</Card>\n<Card title=\"OpenAI\">\n    Direct integration for GPT models, embeddings, and assistants. Set `OPENAI_API_KEY` in your environment.\n</Card>\n<Card title=\"Anthropic\">\n    Claude models for chat and function calling. Requires `ANTHROPIC_API_KEY`.\n</Card>\n<Card title=\"Google AI\">\n    Vertex AI/Gemini models. Configure `GOOGLE_AI_API_KEY`.\n</Card>\n</CardGroup>\n\n---\n\n## Databases & Storage\n\n<CardGroup cols={2}>\n<Card title=\"Emergent Storage\">\n    Built-in file & media storage for uploads (images, videos, files), no external account needed.\n</Card>\n</CardGroup>\n\n---\n\n## Payment & Commerce\n\n<CardGroup cols={2}>\n<Card title=\"Stripe\">\n    Accept payments, manage subscriptions, and handle billing. Set `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY`.\n</Card>\n<Card title=\"PayPal\">\n    Alternative payment gateway. Configure `PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET`.\n</Card>\n<Card title=\"Shopify\">\n    E-commerce store integration. Requires `SHOPIFY_STORE_URL` and `SHOPIFY_ACCESS_TOKEN`.\n</Card>\n<Card title=\"Razorpay\">\n    Accept payments in India, UPI, cards, netbanking and wallets. Ask the agent to add Razorpay, then set your keys in the Secrets tab (click **Preview**, then **Manage**).\n</Card>\n<Card title=\"Paystack\">\n    Accept payments across African markets, cards, bank transfer, mobile money and more. Ask the agent to add Paystack, then set your keys in the Secrets tab (click **Preview**, then **Manage**).\n</Card>\n</CardGroup>\n\n---\n\n## Communication & Messaging\n\n<CardGroup cols={2}>\n<Card title=\"SendGrid\">\n    Transactional email delivery. Set `SENDGRID_API_KEY`.\n</Card>\n<Card title=\"Twilio\">\n    SMS, voice, and WhatsApp messaging. Requires `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`.\n</Card>\n<Card title=\"Resend\">\n    Send emails from your app. Emergent-managed - add it from the Integrations panel (Preview → Manage), no API key needed. Full-stack web apps only (not available on mobile/Expo projects).\n</Card>\n</CardGroup>\n\n---\n\n## Authentication & Identity\n\n<CardGroup cols={2}>\n<Card title=\"Emergent Auth\">\n    Built-in sign-in, email & password and Google, with no API keys to configure.\n</Card>\n</CardGroup>\n\n---\n\n## How to add an integration\n\n<Steps>\n<Step title=\"Open integrations\">\n    Navigate to **Preview → Manage → Integrations** in your workspace, or ask the agent to add the integration for you.\n</Step>\n  \n<Step title=\"Provide the required keys\">\n    The agent will ask you for the required integration keys and secret values, then securely add and wire them into the integration automatically.\n</Step>\n  \n<Step title=\"Re-publish\">\n    Re-publish your app to apply the integration and environment changes.\n</Step>\n</Steps>\n\n<Warning>\nNever commit API keys to your repository or share them in chat. Always use environment variables.\n</Warning>\n\n---\n\n## Request a new integration\n\nIf you need an integration not listed here, describe it in chat and the AI agents will attempt to configure it using standard REST APIs or SDKs. For official platform support, contact the Emergent team or submit a feature request.\n\n<Tip>\nMost modern APIs work out-of-the-box by setting the appropriate environment variables and installing the vendor's SDK through chat (e.g., \"install the Notion SDK and connect to my workspace\").\n</Tip>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Integrations & scheduled tasks\" href=\"/integrations-scheduled-tasks\">\n    Learn how integrations work and how to set up recurring jobs.\n</Card>\n<Card title=\"A tour of the workspace\" href=\"/a-tour-of-the-workspace\">\n    Overview of the workspace UI and where to manage environment variables.\n</Card>\n</CardGroup>","published_title":"Key integrations catalogue","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"dc8d8cd1-3bfa-426f-8928-dbf9fb985280","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Stripe","slug":"stripe","content":"## Overview\n\nStripe is a payment processing platform that enables your Emergent app to accept payments, manage subscriptions, and handle complex billing scenarios. This guide walks you through integrating Stripe into your project using Emergent's natural language interface.\n\n<Note>\nStripe integration requires a Stripe account. You can create one at [stripe.com](https://stripe.com) and use test mode during development at no cost.\n</Note>\n\n## Prerequisites\n\nBefore integrating Stripe, ensure you have:\n\n- A Stripe account (test mode credentials work for development)\n- Your Stripe **Publishable Key** (starts with `pk_`)\n- Your Stripe **Secret Key** (starts with `sk_`)\n- A clear understanding of what payment flows your app needs (one-time payments, subscriptions, etc.)\n\n## Integration Steps\n\n<Steps>\n<Step title=\"Tell Emergent about your payment needs\">\nDescribe your payment requirements in natural language. Be specific about what you want to accomplish:\n\n**Example prompts:**\n\n- \"Add Stripe payment processing. Users should be able to purchase credits for $10, $25, or $50.\"\n- \"Integrate Stripe subscriptions with three tiers: Basic ($9/month), Pro ($29/month), and Enterprise ($99/month).\"\n- \"Add a checkout flow where users can buy individual products from a catalog.\"\n\nEmergent's agents will generate the appropriate Stripe integration code, including client-side checkout components and server-side payment endpoints.\n</Step>\n\n<Step title=\"Use the managed Stripe sandbox or provide your own keys\">\nEmergent provides a managed Stripe sandbox that automatically injects read-only `STRIPE_*` keys (`STRIPE_MODE`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_ACCOUNT_ID`) into your project.\n\nTo use the managed sandbox, claim it and complete KYC. Going live is platform-handled after KYC.\n\nAlternatively, you can unlink the sandbox and provide your own Stripe keys (BYOK).\n\n<Warning>\nNever commit secret keys to your codebase. Use Emergent's environment variable system to keep credentials secure.\n</Warning>\n\nThe agent will configure the required credentials as secure environment variables accessible to your backend code.\n</Step>\n\n<Step title=\"Test the payment flow\">\nAsk Emergent to test the integration:\n\n> Test the Stripe checkout flow\n\nThe agents will verify that:\n\n- Checkout sessions are created correctly\n- Payment confirmation is handled correctly\n- Success and cancellation redirects work as expected\n\nUse [Stripe's test card numbers](https://stripe.com/docs/testing) to simulate successful and failed payments during testing.\n</Step>\n\n<Step title=\"Configure webhooks - BYOK only\">\nIf you're using the **managed Stripe sandbox**, webhook handling is already configured by Emergent. **You don't need to manually configure a webhook in the Stripe Dashboard.**\n\nIf you're using **your own Stripe keys (BYOK)**, configure webhook handling for your integration.\n\nTell Emergent:\n\n> Set up Stripe webhooks to handle payment confirmation and subscription events\n\nThe agent will:\n\n- Create the webhook endpoint in your backend\n- Parse and verify Stripe webhook signatures\n- Update your database based on payment events\n- Provide the webhook URL to add in your **Stripe Dashboard → Developers → Webhooks**\n</Step>\n\n<Step title=\"Publish to production\">\n**Managed Stripe sandbox:**  \nAfter KYC approval, Emergent handles the transition from sandbox to live Stripe credentials.\n\n**BYOK:**  \nWhen you're ready to go live:\n\n1. Update the webhook endpoint in your Stripe Dashboard to point to your production domain.\n\n2. Ensure your custom domain is configured, if using one.\n\n3. Provide your live Stripe keys after the first publish in the secrets panel(Preview → Manage → Secrets) and then re-publish\n</Step>\n</Steps>\n\n## Common Payment Patterns\n\nFor simple product purchases or one-off charges:\n\n> Add a \"Buy Now\" button that charges $49.99 for premium access\n\nEmergent will create a Stripe Checkout session that handles the entire payment flow, including success/cancel redirects.\n\nFor recurring billing:\n\n> Create a subscription system with monthly and annual billing options\n\nThe agents will set up Stripe subscription products, handle plan changes, and manage billing cycles.\n\nFor metered or consumption-based pricing:\n\n> Set up usage-based billing where users are charged $0.10 per API call\n\nThis creates a metered billing system that reports usage to Stripe and bills accordingly.\n\nFor simple no-code payment collection:\n\n> Generate a Stripe payment link for a $199 consulting package\n\nReturns a shareable URL that you can use in emails, marketing pages, or chat messages.\n\n## Refining Your Integration\n\nAfter the initial setup, you can refine the integration with natural language:\n\n- \"Add a customer portal where users can manage their subscription and update payment methods\"\n- \"Show a payment history page with all past invoices\"\n- \"Add a discount code field to the checkout\"\n- \"Send a confirmation email after successful payment\"\n- \"Store customer payment info for future purchases\"\n\n## Security Best Practices\n\n<CardGroup cols={2}>\n<Card title=\"Use webhooks\">\nDon't rely solely on client-side success callbacks. Webhooks provide authoritative, server-verified payment confirmation.\n</Card>\n\n<Card title=\"Validate amounts server-side\">\nNever trust payment amounts from the client. Always define prices and calculations in backend code.\n</Card>\n\n<Card title=\"Test failure scenarios\">\nUse Stripe's test cards to simulate declined payments, insufficient funds, and fraud scenarios.\n</Card>\n\n<Card title=\"Handle idempotency\">\nStripe operations should be idempotent to prevent duplicate charges if requests are retried.\n</Card>\n</CardGroup>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Payments succeed but webhooks aren't received | Verify your webhook URL is publicly accessible and correctly configured in the Stripe Dashboard. In Emergent, your app runs as a cloud preview with a public URL, you can use that URL directly for webhook testing rather than forwarding to localhost. Ask Emergent: `Set up webhook testing for Stripe` |\n| Invalid API key errors | Double-check that you're using the correct key type (publishable keys for frontend, secret keys for backend) and that they match your Stripe account mode (test vs. live). Note that the managed sandbox injects read-only keys; to use your own, unlink the sandbox first. |\n| Checkout session expires too quickly | Stripe Checkout sessions expire after 24 hours by default. If users abandon checkout frequently, consider storing session state and allowing them to resume, or create a new session on return. |\n| Currency or region issues | Stripe supports 135+ currencies but availability varies by country. Tell Emergent which currencies and regions you need to support: `Configure Stripe to accept EUR and GBP in addition to USD` |\n\n## Next Steps\n\n<CardGroup cols={2}>\n<Card title=\"Database Integration\" href=\"/database-mongodb\">\nStore payment records and subscription status in your MongoDB database\n</Card>\n\n<Card title=\"Custom Domain\" href=\"/custom-domain\">\nConfigure a custom domain for professional payment page branding\n</Card>\n</CardGroup>\n\n<Info>\nStripe's pricing is pay-as-you-go with no monthly fees. You're charged a percentage of each successful transaction. Check [Stripe's pricing page](https://stripe.com/pricing) for current rates in your region.\n</Info>","order":57,"parent_id":null,"icon":"tag","description":"Stripe","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.731864+00:00","published_at":"2026-09-22T06:19:16.731864+00:00","published_content":"## Overview\n\nStripe is a payment processing platform that enables your Emergent app to accept payments, manage subscriptions, and handle complex billing scenarios. This guide walks you through integrating Stripe into your project using Emergent's natural language interface.\n\n<Note>\nStripe integration requires a Stripe account. You can create one at [stripe.com](https://stripe.com) and use test mode during development at no cost.\n</Note>\n\n## Prerequisites\n\nBefore integrating Stripe, ensure you have:\n\n- A Stripe account (test mode credentials work for development)\n- Your Stripe **Publishable Key** (starts with `pk_`)\n- Your Stripe **Secret Key** (starts with `sk_`)\n- A clear understanding of what payment flows your app needs (one-time payments, subscriptions, etc.)\n\n## Integration Steps\n\n<Steps>\n<Step title=\"Tell Emergent about your payment needs\">\nDescribe your payment requirements in natural language. Be specific about what you want to accomplish:\n\n**Example prompts:**\n\n- \"Add Stripe payment processing. Users should be able to purchase credits for $10, $25, or $50.\"\n- \"Integrate Stripe subscriptions with three tiers: Basic ($9/month), Pro ($29/month), and Enterprise ($99/month).\"\n- \"Add a checkout flow where users can buy individual products from a catalog.\"\n\nEmergent's agents will generate the appropriate Stripe integration code, including client-side checkout components and server-side payment endpoints.\n</Step>\n\n<Step title=\"Use the managed Stripe sandbox or provide your own keys\">\nEmergent provides a managed Stripe sandbox that automatically injects read-only `STRIPE_*` keys (`STRIPE_MODE`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_ACCOUNT_ID`) into your project.\n\nTo use the managed sandbox, claim it and complete KYC. Going live is platform-handled after KYC.\n\nAlternatively, you can unlink the sandbox and provide your own Stripe keys (BYOK).\n\n<Warning>\nNever commit secret keys to your codebase. Use Emergent's environment variable system to keep credentials secure.\n</Warning>\n\nThe agent will configure the required credentials as secure environment variables accessible to your backend code.\n</Step>\n\n<Step title=\"Test the payment flow\">\nAsk Emergent to test the integration:\n\n> Test the Stripe checkout flow\n\nThe agents will verify that:\n\n- Checkout sessions are created correctly\n- Payment confirmation is handled correctly\n- Success and cancellation redirects work as expected\n\nUse [Stripe's test card numbers](https://stripe.com/docs/testing) to simulate successful and failed payments during testing.\n</Step>\n\n<Step title=\"Configure webhooks - BYOK only\">\nIf you're using the **managed Stripe sandbox**, webhook handling is already configured by Emergent. **You don't need to manually configure a webhook in the Stripe Dashboard.**\n\nIf you're using **your own Stripe keys (BYOK)**, configure webhook handling for your integration.\n\nTell Emergent:\n\n> Set up Stripe webhooks to handle payment confirmation and subscription events\n\nThe agent will:\n\n- Create the webhook endpoint in your backend\n- Parse and verify Stripe webhook signatures\n- Update your database based on payment events\n- Provide the webhook URL to add in your **Stripe Dashboard → Developers → Webhooks**\n</Step>\n\n<Step title=\"Publish to production\">\n**Managed Stripe sandbox:**  \nAfter KYC approval, Emergent handles the transition from sandbox to live Stripe credentials.\n\n**BYOK:**  \nWhen you're ready to go live:\n\n1. Update the webhook endpoint in your Stripe Dashboard to point to your production domain.\n\n2. Ensure your custom domain is configured, if using one.\n\n3. Provide your live Stripe keys after the first publish in the secrets panel(Preview → Manage → Secrets) and then re-publish\n</Step>\n</Steps>\n\n## Common Payment Patterns\n\nFor simple product purchases or one-off charges:\n\n> Add a \"Buy Now\" button that charges $49.99 for premium access\n\nEmergent will create a Stripe Checkout session that handles the entire payment flow, including success/cancel redirects.\n\nFor recurring billing:\n\n> Create a subscription system with monthly and annual billing options\n\nThe agents will set up Stripe subscription products, handle plan changes, and manage billing cycles.\n\nFor metered or consumption-based pricing:\n\n> Set up usage-based billing where users are charged $0.10 per API call\n\nThis creates a metered billing system that reports usage to Stripe and bills accordingly.\n\nFor simple no-code payment collection:\n\n> Generate a Stripe payment link for a $199 consulting package\n\nReturns a shareable URL that you can use in emails, marketing pages, or chat messages.\n\n## Refining Your Integration\n\nAfter the initial setup, you can refine the integration with natural language:\n\n- \"Add a customer portal where users can manage their subscription and update payment methods\"\n- \"Show a payment history page with all past invoices\"\n- \"Add a discount code field to the checkout\"\n- \"Send a confirmation email after successful payment\"\n- \"Store customer payment info for future purchases\"\n\n## Security Best Practices\n\n<CardGroup cols={2}>\n<Card title=\"Use webhooks\">\nDon't rely solely on client-side success callbacks. Webhooks provide authoritative, server-verified payment confirmation.\n</Card>\n\n<Card title=\"Validate amounts server-side\">\nNever trust payment amounts from the client. Always define prices and calculations in backend code.\n</Card>\n\n<Card title=\"Test failure scenarios\">\nUse Stripe's test cards to simulate declined payments, insufficient funds, and fraud scenarios.\n</Card>\n\n<Card title=\"Handle idempotency\">\nStripe operations should be idempotent to prevent duplicate charges if requests are retried.\n</Card>\n</CardGroup>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Payments succeed but webhooks aren't received | Verify your webhook URL is publicly accessible and correctly configured in the Stripe Dashboard. In Emergent, your app runs as a cloud preview with a public URL, you can use that URL directly for webhook testing rather than forwarding to localhost. Ask Emergent: `Set up webhook testing for Stripe` |\n| Invalid API key errors | Double-check that you're using the correct key type (publishable keys for frontend, secret keys for backend) and that they match your Stripe account mode (test vs. live). Note that the managed sandbox injects read-only keys; to use your own, unlink the sandbox first. |\n| Checkout session expires too quickly | Stripe Checkout sessions expire after 24 hours by default. If users abandon checkout frequently, consider storing session state and allowing them to resume, or create a new session on return. |\n| Currency or region issues | Stripe supports 135+ currencies but availability varies by country. Tell Emergent which currencies and regions you need to support: `Configure Stripe to accept EUR and GBP in addition to USD` |\n\n## Next Steps\n\n<CardGroup cols={2}>\n<Card title=\"Database Integration\" href=\"/database-mongodb\">\nStore payment records and subscription status in your MongoDB database\n</Card>\n\n<Card title=\"Custom Domain\" href=\"/custom-domain\">\nConfigure a custom domain for professional payment page branding\n</Card>\n</CardGroup>\n\n<Info>\nStripe's pricing is pay-as-you-go with no monthly fees. You're charged a percentage of each successful transaction. Check [Stripe's pricing page](https://stripe.com/pricing) for current rates in your region.\n</Info>","published_title":"Stripe","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"52f8e63f-5635-4d67-9b3f-7302bd0bfe14","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Razorpay","slug":"razorpay","content":"## Overview\n\nRazorpay is a payment gateway that enables businesses in India to accept, process, and disburse payments online. This guide walks you through integrating Razorpay into your Emergent application to accept payments from customers.\n\n<Note>\nRazorpay is primarily designed for businesses operating in India. Ensure your business is eligible and complies with Razorpay's registration requirements before integrating.\n</Note>\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- A Razorpay account ([sign up here](https://razorpay.com))\n- Your Razorpay **API Key** and **API Secret** from the Razorpay Dashboard\n- Basic understanding of payment flows (checkout, webhooks, order verification)\n\n## Getting Your Razorpay Credentials\n\n<Steps>\n<Step title=\"Log into Razorpay Dashboard\">\nSign in to your [Razorpay Dashboard](https://dashboard.razorpay.com/?utm_source=chatgpt.com).\n</Step>\n\n<Step title=\"Access API Keys\">\nGo to **Settings → API Keys**.\n</Step>\n\n<Step title=\"Generate test keys\">\nGenerate your **test-mode** Key ID and Key Secret.\n\n<Warning>\nThe **Key Secret** is shown only once. Store it securely.\n</Warning>\n</Step>\n\n<Step title=\"Copy test credentials\">\n- **Key ID** - starts with `rzp_test_`\n- **Key Secret**\n</Step>\n</Steps>\n\n## Configure Razorpay in Emergent\n\n<Steps>\n<Step title=\"Describe your payment flow\">\nTell Emergent what you want to build with Razorpay.\n</Step>\n\n<Step title=\"Provide your test credentials\">\nWhen Emergent asks, provide your **test-mode Key ID and Key Secret**. The agent will securely configure and wire them into the project.\n</Step>\n\n<Step title=\"Configure the webhook\">\nWhen Emergent provides the webhook endpoint and asks for the webhook secret, configure them in Razorpay and provide the secret to the agent.\n</Step>\n\n<Step title=\"Implement and test the integration\">\nThe agent will implement the checkout and payment verification flow.\n</Step>\n</Steps>\n\n## Testing in Development\n\n<Steps>\n<Step title=\"Initiate checkout\">\nTest a payment using Razorpay Test Mode.\n</Step>\n\n<Step title=\"Verify payment\">\nConfirm the payment is verified server-side.\n</Step>\n\n<Step title=\"Verify webhook\">\nConfirm the webhook is received and processed correctly.\n</Step>\n\n<Step title=\"Verify in Dashboard\">\nCheck the test payment in the Razorpay Dashboard.\n</Step>\n</Steps>\n\n## Going Live\n\n<Steps>\n<Step title=\"Complete KYC and activation\">\nComplete Razorpay's required KYC and account activation.\n</Step>\n\n<Step title=\"Generate live keys\">\nGenerate your **live-mode** Key ID and Key Secret.\n</Step>\n\n<Step title=\"Update production credentials\">\nAfter the first publish, update the **live Key ID and Key Secret** in the **Emergent Secret Panel**, then re-publish the app.\n</Step>\n\n<Step title=\"Configure the production webhook\">\nConfigure the production webhook and provide the webhook secret to Emergent when requested.\n</Step>\n\n<Step title=\"Publish the app\">\nPublish the app and verify a real payment flow.\n</Step>\n</Steps>\n\n## Common Use Cases\n\n<CardGroup cols={2}>\n<Card title=\"Subscriptions\">\nUse Razorpay's Subscriptions API to bill customers on a recurring basis (monthly, annually, etc.).\n</Card>\n\n<Card title=\"Payment Links\">\nGenerate shareable payment links for quick invoicing without building a checkout UI.\n</Card>\n\n<Card title=\"Refunds\">\nIssue full or partial refunds programmatically via the Razorpay API.\n</Card>\n\n<Card title=\"Smart Collect\">\nAccept payments via UPI, bank transfer, or virtual accounts for B2B scenarios.\n</Card>\n</CardGroup>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Payment succeeds but webhook isn't received | Confirm your webhook URL is publicly accessible (not `localhost` in production). Check the **Webhooks** logs in the Razorpay Dashboard for delivery failures. Verify the endpoint responds with a `200 OK` status. |\n| Signature verification fails | Ensure you're using the correct `key_secret` (test vs. live). Check that the concatenation order matches: `order_id|payment_id`. Confirm no extra whitespace or encoding issues in the signature string. |\n| Checkout modal doesn't open | Verify the Razorpay Checkout.js script is loaded (`https://checkout.razorpay.com/v1/checkout.js`). Check browser console for JavaScript errors. Ensure `key`, `amount`, and `order_id` are all correctly populated. |\n| Amount mismatch errors | Razorpay amounts are in the smallest currency unit (paise for INR). For ₹100, send `10000` (100 × 100). Double-check your multiplication in both order creation and checkout. |\n\n## Additional Resources\n\n- [Razorpay API Documentation](https://razorpay.com/docs/api/)\n- [Checkout.js Integration Guide](https://razorpay.com/docs/payments/payment-gateway/web-integration/)\n- [Webhooks Reference](https://razorpay.com/docs/webhooks/)\n- [Razorpay Dashboard](https://dashboard.razorpay.com)\n\n---\n\nNeed help integrating Razorpay? Describe your payment flow in the Emergent chat, and the AI agents will generate the necessary backend routes, frontend UI, and webhook handlers for you.","order":58,"parent_id":null,"icon":"tag","description":"Razorpay","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.734134+00:00","published_at":"2026-09-22T06:19:16.734134+00:00","published_content":"## Overview\n\nRazorpay is a payment gateway that enables businesses in India to accept, process, and disburse payments online. This guide walks you through integrating Razorpay into your Emergent application to accept payments from customers.\n\n<Note>\nRazorpay is primarily designed for businesses operating in India. Ensure your business is eligible and complies with Razorpay's registration requirements before integrating.\n</Note>\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- A Razorpay account ([sign up here](https://razorpay.com))\n- Your Razorpay **API Key** and **API Secret** from the Razorpay Dashboard\n- Basic understanding of payment flows (checkout, webhooks, order verification)\n\n## Getting Your Razorpay Credentials\n\n<Steps>\n<Step title=\"Log into Razorpay Dashboard\">\nSign in to your [Razorpay Dashboard](https://dashboard.razorpay.com/?utm_source=chatgpt.com).\n</Step>\n\n<Step title=\"Access API Keys\">\nGo to **Settings → API Keys**.\n</Step>\n\n<Step title=\"Generate test keys\">\nGenerate your **test-mode** Key ID and Key Secret.\n\n<Warning>\nThe **Key Secret** is shown only once. Store it securely.\n</Warning>\n</Step>\n\n<Step title=\"Copy test credentials\">\n- **Key ID** - starts with `rzp_test_`\n- **Key Secret**\n</Step>\n</Steps>\n\n## Configure Razorpay in Emergent\n\n<Steps>\n<Step title=\"Describe your payment flow\">\nTell Emergent what you want to build with Razorpay.\n</Step>\n\n<Step title=\"Provide your test credentials\">\nWhen Emergent asks, provide your **test-mode Key ID and Key Secret**. The agent will securely configure and wire them into the project.\n</Step>\n\n<Step title=\"Configure the webhook\">\nWhen Emergent provides the webhook endpoint and asks for the webhook secret, configure them in Razorpay and provide the secret to the agent.\n</Step>\n\n<Step title=\"Implement and test the integration\">\nThe agent will implement the checkout and payment verification flow.\n</Step>\n</Steps>\n\n## Testing in Development\n\n<Steps>\n<Step title=\"Initiate checkout\">\nTest a payment using Razorpay Test Mode.\n</Step>\n\n<Step title=\"Verify payment\">\nConfirm the payment is verified server-side.\n</Step>\n\n<Step title=\"Verify webhook\">\nConfirm the webhook is received and processed correctly.\n</Step>\n\n<Step title=\"Verify in Dashboard\">\nCheck the test payment in the Razorpay Dashboard.\n</Step>\n</Steps>\n\n## Going Live\n\n<Steps>\n<Step title=\"Complete KYC and activation\">\nComplete Razorpay's required KYC and account activation.\n</Step>\n\n<Step title=\"Generate live keys\">\nGenerate your **live-mode** Key ID and Key Secret.\n</Step>\n\n<Step title=\"Update production credentials\">\nAfter the first publish, update the **live Key ID and Key Secret** in the **Emergent Secret Panel**, then re-publish the app.\n</Step>\n\n<Step title=\"Configure the production webhook\">\nConfigure the production webhook and provide the webhook secret to Emergent when requested.\n</Step>\n\n<Step title=\"Publish the app\">\nPublish the app and verify a real payment flow.\n</Step>\n</Steps>\n\n## Common Use Cases\n\n<CardGroup cols={2}>\n<Card title=\"Subscriptions\">\nUse Razorpay's Subscriptions API to bill customers on a recurring basis (monthly, annually, etc.).\n</Card>\n\n<Card title=\"Payment Links\">\nGenerate shareable payment links for quick invoicing without building a checkout UI.\n</Card>\n\n<Card title=\"Refunds\">\nIssue full or partial refunds programmatically via the Razorpay API.\n</Card>\n\n<Card title=\"Smart Collect\">\nAccept payments via UPI, bank transfer, or virtual accounts for B2B scenarios.\n</Card>\n</CardGroup>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Payment succeeds but webhook isn't received | Confirm your webhook URL is publicly accessible (not `localhost` in production). Check the **Webhooks** logs in the Razorpay Dashboard for delivery failures. Verify the endpoint responds with a `200 OK` status. |\n| Signature verification fails | Ensure you're using the correct `key_secret` (test vs. live). Check that the concatenation order matches: `order_id|payment_id`. Confirm no extra whitespace or encoding issues in the signature string. |\n| Checkout modal doesn't open | Verify the Razorpay Checkout.js script is loaded (`https://checkout.razorpay.com/v1/checkout.js`). Check browser console for JavaScript errors. Ensure `key`, `amount`, and `order_id` are all correctly populated. |\n| Amount mismatch errors | Razorpay amounts are in the smallest currency unit (paise for INR). For ₹100, send `10000` (100 × 100). Double-check your multiplication in both order creation and checkout. |\n\n## Additional Resources\n\n- [Razorpay API Documentation](https://razorpay.com/docs/api/)\n- [Checkout.js Integration Guide](https://razorpay.com/docs/payments/payment-gateway/web-integration/)\n- [Webhooks Reference](https://razorpay.com/docs/webhooks/)\n- [Razorpay Dashboard](https://dashboard.razorpay.com)\n\n---\n\nNeed help integrating Razorpay? Describe your payment flow in the Emergent chat, and the AI agents will generate the necessary backend routes, frontend UI, and webhook handlers for you.","published_title":"Razorpay","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"d9d4b9d4-97d3-468a-ad91-5be0280a84ed","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Paystack","slug":"paystack","content":"## Overview\n\nPaystack is a modern payment gateway that makes it easy to accept payments from customers across Africa. This guide shows you how to integrate Paystack into your Emergent app so you can collect payments, manage subscriptions, and handle transactions.\n\nWhen you connect Paystack, your app can process card payments, bank transfers, mobile money, and other local payment methods supported across African markets.\n\n## Before you begin\n\nYou'll need:\n\n- A [Paystack account](https://paystack.com) (sign up is free)\n- Your Paystack API keys (available in your Paystack dashboard under Settings → API Keys & Webhooks)\n- An Emergent app that needs payment functionality\n\n<Info>\nPaystack provides both **test keys** (for development) and **live keys** (for production). Start with test keys while building and testing your integration.\n</Info>\n\n## Add Paystack to your app\n\n<Steps>\n<Step title=\"Tell Emergent you want to use Paystack\">\nIn your app's chat, describe what you want to build:\n\n> \"Add Paystack payment integration. I want to accept card payments and generate payment links for customers.\"\n\nBe specific about your use case - for example, one-time payments, subscriptions, or donation flows.\n</Step>\n\n<Step title=\"Provide your API keys\">\nEmergent will prompt you for your Paystack keys. You'll need:\n\n- **Public key** - safe to expose in your frontend code\n- **Secret key** - kept secure on the backend; never expose this in client-side code\n\nCopy these from your Paystack dashboard (Settings → API Keys & Webhooks) and paste them when prompted.\n</Step>\n\n<Step title=\"Configure webhook endpoints\">\nPaystack sends notifications (webhooks) when payment events occur - successful charges, failed transactions, subscription renewals, etc.\n\nEmergent will generate a webhook URL for your app. Copy this URL and add it in your Paystack dashboard:\n\n1. Go to Settings → API Keys & Webhooks\n2. Scroll to **Webhook URL**\n3. Paste your Emergent webhook URL\n4. Save changes\n\nThis ensures your app receives real-time updates about payment status.\n</Step>\n\n<Step title=\"Test the integration\">\nUse Paystack's test card numbers to verify everything works:\n\n- **Successful payment**: `4084 0840 8408 4081` (any future expiry, any CVV)\n- **Declined payment**: `5060 6666 6666 6666 64`\n\nProcess a test transaction in your app and confirm that payment status updates correctly.\n</Step>\n\n<Step title=\"Go live\">\nWhen you're ready for production:\n\n- After the first publish, replace the test keys with live keys in the Secrets panel(Preview → Manage → Secrets)\n- Ensure your Paystack account is fully activated (business verification complete)\n- Confirm your webhook URL is configured with your live keys\n- Re-publish the app to apply the live keys\n</Step>\n</Steps>\n\n## Common use cases\n\n<Tabs>\n<Tab title=\"One-time payments\">\nFor selling products or services with a single charge:\n\n- Initialize a transaction with an amount and customer email\n- Redirect the customer to Paystack's secure checkout\n- Handle the callback when payment succeeds or fails\n- Confirm transaction status via webhook before fulfilling the order\n</Tab>\n\n<Tab title=\"Subscription billing\">\nFor recurring revenue models:\n\n- Create a **Plan** in your Paystack dashboard (defines amount and billing interval)\n- Subscribe customers to the plan via your app\n- Paystack automatically charges the customer on each billing cycle\n- Handle `subscription.create`, `charge.success`, and `subscription.disable` webhooks\n</Tab>\n\n<Tab title=\"Payment links\">\nFor no-code payment collection:\n\n- Generate a Paystack payment link in your app\n- Share the link via email, SMS, or messaging apps\n- Customers pay without needing to visit your website\n- Track payments in your Paystack dashboard or via webhooks\n</Tab>\n\n<Tab title=\"Split payments\">\nFor marketplaces or platforms with multiple vendors:\n\n- Set up **Subaccounts** for each vendor in Paystack\n- Route a percentage of each transaction to the subaccount\n- Paystack handles the splits automatically\n- Each vendor can withdraw their balance independently\n</Tab>\n</Tabs>\n\n## Supported payment methods\n\nPaystack supports different payment methods by country. The available channels are:\n\n- **Card**: all markets.\n- **Pay-with-Bank**: Nigeria.\n- **Pay-with-Transfer**: Nigeria and Ghana.\n- **USSD**: Nigeria.\n- **Mobile Money**: Ghana (MTN, AT Money & Airtel Money, Telecel), Kenya (M-Pesa, Airtel Money), and Côte d'Ivoire (MTN, Orange, Wave).\n- **Pay with Pesalink**: Kenya. Instant bank transfers; requires enablement by Paystack support, and Diamond Trust Bank accounts can't pay via this channel.\n- **Instant EFT (Ozow)**: South Africa.\n- **Capitec Pay**: South Africa.\n- **QR (SnapScan / Scan to Pay)**: South Africa.\n\n<Tip>\nEnable multiple payment methods to maximize conversion. Customers can choose their preferred option at checkout.\n</Tip>\n\n## Webhook events\n\nYour app receives these common events from Paystack:\n\n<AccordionGroup>\n<Accordion title=\"charge.success\">\nFired when a payment is successfully completed. Use this to fulfill orders, grant access, or trigger downstream workflows. Always verify the transaction amount and status before taking action.\n</Accordion>\n\n<Accordion title=\"charge.failed\">\nSent when a payment attempt fails (insufficient funds, incorrect PIN, etc.). You might want to notify the customer or offer alternative payment methods.\n</Accordion>\n\n<Accordion title=\"transfer.success\">\nTriggered when you send money to a customer (refunds, payouts, etc.). Useful for confirming disbursements in marketplace or payout scenarios.\n</Accordion>\n\n<Accordion title=\"subscription.create\">\nFired when a customer is subscribed to a plan. Update your database to reflect active subscription status.\n</Accordion>\n\n<Accordion title=\"subscription.disable\">\nSent when a subscription is canceled (by the customer or due to failed payments). Revoke access or notify the customer as appropriate.\n</Accordion>\n</AccordionGroup>\n\n<Info>\nPaystack webhooks include a signature header (`x-paystack-signature`) for verification. Emergent sets up signature verification into your code so your app verifies events are authentic.\n</Info>\n\n## Testing and troubleshooting\n\n### Test mode vs. live mode\n\nAlways develop and test with **test keys**. Test mode has no financial impact - transactions are simulated and no real money moves. When you switch to **live keys**, every transaction is real.\n\n### Common issues\n\n| Issue | Solution |\n| --- | --- |\n| Webhook not receiving events | Confirm the webhook URL in your Paystack dashboard matches the one Emergent provided - Check that your app is published and accessible (your cloud preview at `{slug}.preview.emergentagent.com` is a public URL reachable by webhooks) - Verify the webhook signature validation is enabled |\n| Transactions showing as pending | Bank transfers and some mobile money payments require manual confirmation - Check the Paystack dashboard for transaction status - Set up webhook listeners for `charge.success` to know when payment clears |\n| Payment page not loading | Ensure your public key is correctly configured in the frontend - Check browser console for JavaScript errors - Verify the transaction amount is valid (Paystack requires amounts in kobo/pesewas - smallest currency unit) |\n\n### Testing tools\n\nPaystack provides a **Test Mode Dashboard** where you can:\n\n- View all test transactions\n- Manually trigger webhook events\n- Simulate different payment outcomes (success, decline, timeout)\n- Inspect API requests and responses\n\nUse these tools to verify your integration handles all scenarios correctly before going live.\n\n## Security best practices\n\n<CardGroup cols={2}>\n<Card title=\"Protect your secret key\" icon=\"key\">\nNever commit secret keys to version control or expose them in client-side code. Emergent stores them securely as environment variables.\n</Card>\n\n<Card title=\"Validate webhooks\" icon=\"shield-check\">\nAlways verify the `x-paystack-signature` header on incoming webhooks. This prevents malicious actors from spoofing payment events.\n</Card>\n\n<Card title=\"Confirm on the backend\" icon=\"server\">\nAfter a customer completes checkout, verify the transaction status by querying Paystack's API from your backend - don't trust frontend callbacks alone.\n</Card>\n\n<Card title=\"Use HTTPS\" icon=\"lock\">\nEnsure your webhook endpoint uses HTTPS. Paystack will not send events to insecure HTTP URLs in live mode.\n</Card>\n</CardGroup>\n\n## Pricing and fees\n\nPaystack charges a percentage of each successful transaction. Fees vary by country and payment method:\n\n- **Nigeria**: 1.5% capped at ₦2,000\n- **Ghana**: 1.95% (no cap)\n- **South Africa**: 2.9% (no cap)\n\nAdditional fees may apply for international cards or specific payment methods. Check [Paystack's pricing page](https://paystack.com/pricing) for current rates.\n\n<Note>\nThere are no setup fees, monthly charges, or hidden costs. You only pay when you successfully collect a payment.\n</Note>\n\n## Resources\n\n- [Paystack Documentation](https://paystack.com/docs)\n- [Paystack API Reference](https://paystack.com/docs/api)\n- [Test Cards and Accounts](https://paystack.com/docs/payments/test-payments)\n- [Webhook Event Reference](https://paystack.com/docs/payments/webhooks)","order":59,"parent_id":null,"icon":"tag","description":"Paystack","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.887173+00:00","published_at":"2026-09-22T06:19:16.887173+00:00","published_content":"## Overview\n\nPaystack is a modern payment gateway that makes it easy to accept payments from customers across Africa. This guide shows you how to integrate Paystack into your Emergent app so you can collect payments, manage subscriptions, and handle transactions.\n\nWhen you connect Paystack, your app can process card payments, bank transfers, mobile money, and other local payment methods supported across African markets.\n\n## Before you begin\n\nYou'll need:\n\n- A [Paystack account](https://paystack.com) (sign up is free)\n- Your Paystack API keys (available in your Paystack dashboard under Settings → API Keys & Webhooks)\n- An Emergent app that needs payment functionality\n\n<Info>\nPaystack provides both **test keys** (for development) and **live keys** (for production). Start with test keys while building and testing your integration.\n</Info>\n\n## Add Paystack to your app\n\n<Steps>\n<Step title=\"Tell Emergent you want to use Paystack\">\nIn your app's chat, describe what you want to build:\n\n> \"Add Paystack payment integration. I want to accept card payments and generate payment links for customers.\"\n\nBe specific about your use case - for example, one-time payments, subscriptions, or donation flows.\n</Step>\n\n<Step title=\"Provide your API keys\">\nEmergent will prompt you for your Paystack keys. You'll need:\n\n- **Public key** - safe to expose in your frontend code\n- **Secret key** - kept secure on the backend; never expose this in client-side code\n\nCopy these from your Paystack dashboard (Settings → API Keys & Webhooks) and paste them when prompted.\n</Step>\n\n<Step title=\"Configure webhook endpoints\">\nPaystack sends notifications (webhooks) when payment events occur - successful charges, failed transactions, subscription renewals, etc.\n\nEmergent will generate a webhook URL for your app. Copy this URL and add it in your Paystack dashboard:\n\n1. Go to Settings → API Keys & Webhooks\n2. Scroll to **Webhook URL**\n3. Paste your Emergent webhook URL\n4. Save changes\n\nThis ensures your app receives real-time updates about payment status.\n</Step>\n\n<Step title=\"Test the integration\">\nUse Paystack's test card numbers to verify everything works:\n\n- **Successful payment**: `4084 0840 8408 4081` (any future expiry, any CVV)\n- **Declined payment**: `5060 6666 6666 6666 64`\n\nProcess a test transaction in your app and confirm that payment status updates correctly.\n</Step>\n\n<Step title=\"Go live\">\nWhen you're ready for production:\n\n- After the first publish, replace the test keys with live keys in the Secrets panel(Preview → Manage → Secrets)\n- Ensure your Paystack account is fully activated (business verification complete)\n- Confirm your webhook URL is configured with your live keys\n- Re-publish the app to apply the live keys\n</Step>\n</Steps>\n\n## Common use cases\n\n<Tabs>\n<Tab title=\"One-time payments\">\nFor selling products or services with a single charge:\n\n- Initialize a transaction with an amount and customer email\n- Redirect the customer to Paystack's secure checkout\n- Handle the callback when payment succeeds or fails\n- Confirm transaction status via webhook before fulfilling the order\n</Tab>\n\n<Tab title=\"Subscription billing\">\nFor recurring revenue models:\n\n- Create a **Plan** in your Paystack dashboard (defines amount and billing interval)\n- Subscribe customers to the plan via your app\n- Paystack automatically charges the customer on each billing cycle\n- Handle `subscription.create`, `charge.success`, and `subscription.disable` webhooks\n</Tab>\n\n<Tab title=\"Payment links\">\nFor no-code payment collection:\n\n- Generate a Paystack payment link in your app\n- Share the link via email, SMS, or messaging apps\n- Customers pay without needing to visit your website\n- Track payments in your Paystack dashboard or via webhooks\n</Tab>\n\n<Tab title=\"Split payments\">\nFor marketplaces or platforms with multiple vendors:\n\n- Set up **Subaccounts** for each vendor in Paystack\n- Route a percentage of each transaction to the subaccount\n- Paystack handles the splits automatically\n- Each vendor can withdraw their balance independently\n</Tab>\n</Tabs>\n\n## Supported payment methods\n\nPaystack supports different payment methods by country. The available channels are:\n\n- **Card**: all markets.\n- **Pay-with-Bank**: Nigeria.\n- **Pay-with-Transfer**: Nigeria and Ghana.\n- **USSD**: Nigeria.\n- **Mobile Money**: Ghana (MTN, AT Money & Airtel Money, Telecel), Kenya (M-Pesa, Airtel Money), and Côte d'Ivoire (MTN, Orange, Wave).\n- **Pay with Pesalink**: Kenya. Instant bank transfers; requires enablement by Paystack support, and Diamond Trust Bank accounts can't pay via this channel.\n- **Instant EFT (Ozow)**: South Africa.\n- **Capitec Pay**: South Africa.\n- **QR (SnapScan / Scan to Pay)**: South Africa.\n\n<Tip>\nEnable multiple payment methods to maximize conversion. Customers can choose their preferred option at checkout.\n</Tip>\n\n## Webhook events\n\nYour app receives these common events from Paystack:\n\n<AccordionGroup>\n<Accordion title=\"charge.success\">\nFired when a payment is successfully completed. Use this to fulfill orders, grant access, or trigger downstream workflows. Always verify the transaction amount and status before taking action.\n</Accordion>\n\n<Accordion title=\"charge.failed\">\nSent when a payment attempt fails (insufficient funds, incorrect PIN, etc.). You might want to notify the customer or offer alternative payment methods.\n</Accordion>\n\n<Accordion title=\"transfer.success\">\nTriggered when you send money to a customer (refunds, payouts, etc.). Useful for confirming disbursements in marketplace or payout scenarios.\n</Accordion>\n\n<Accordion title=\"subscription.create\">\nFired when a customer is subscribed to a plan. Update your database to reflect active subscription status.\n</Accordion>\n\n<Accordion title=\"subscription.disable\">\nSent when a subscription is canceled (by the customer or due to failed payments). Revoke access or notify the customer as appropriate.\n</Accordion>\n</AccordionGroup>\n\n<Info>\nPaystack webhooks include a signature header (`x-paystack-signature`) for verification. Emergent sets up signature verification into your code so your app verifies events are authentic.\n</Info>\n\n## Testing and troubleshooting\n\n### Test mode vs. live mode\n\nAlways develop and test with **test keys**. Test mode has no financial impact - transactions are simulated and no real money moves. When you switch to **live keys**, every transaction is real.\n\n### Common issues\n\n| Issue | Solution |\n| --- | --- |\n| Webhook not receiving events | Confirm the webhook URL in your Paystack dashboard matches the one Emergent provided - Check that your app is published and accessible (your cloud preview at `{slug}.preview.emergentagent.com` is a public URL reachable by webhooks) - Verify the webhook signature validation is enabled |\n| Transactions showing as pending | Bank transfers and some mobile money payments require manual confirmation - Check the Paystack dashboard for transaction status - Set up webhook listeners for `charge.success` to know when payment clears |\n| Payment page not loading | Ensure your public key is correctly configured in the frontend - Check browser console for JavaScript errors - Verify the transaction amount is valid (Paystack requires amounts in kobo/pesewas - smallest currency unit) |\n\n### Testing tools\n\nPaystack provides a **Test Mode Dashboard** where you can:\n\n- View all test transactions\n- Manually trigger webhook events\n- Simulate different payment outcomes (success, decline, timeout)\n- Inspect API requests and responses\n\nUse these tools to verify your integration handles all scenarios correctly before going live.\n\n## Security best practices\n\n<CardGroup cols={2}>\n<Card title=\"Protect your secret key\" icon=\"key\">\nNever commit secret keys to version control or expose them in client-side code. Emergent stores them securely as environment variables.\n</Card>\n\n<Card title=\"Validate webhooks\" icon=\"shield-check\">\nAlways verify the `x-paystack-signature` header on incoming webhooks. This prevents malicious actors from spoofing payment events.\n</Card>\n\n<Card title=\"Confirm on the backend\" icon=\"server\">\nAfter a customer completes checkout, verify the transaction status by querying Paystack's API from your backend - don't trust frontend callbacks alone.\n</Card>\n\n<Card title=\"Use HTTPS\" icon=\"lock\">\nEnsure your webhook endpoint uses HTTPS. Paystack will not send events to insecure HTTP URLs in live mode.\n</Card>\n</CardGroup>\n\n## Pricing and fees\n\nPaystack charges a percentage of each successful transaction. Fees vary by country and payment method:\n\n- **Nigeria**: 1.5% capped at ₦2,000\n- **Ghana**: 1.95% (no cap)\n- **South Africa**: 2.9% (no cap)\n\nAdditional fees may apply for international cards or specific payment methods. Check [Paystack's pricing page](https://paystack.com/pricing) for current rates.\n\n<Note>\nThere are no setup fees, monthly charges, or hidden costs. You only pay when you successfully collect a payment.\n</Note>\n\n## Resources\n\n- [Paystack Documentation](https://paystack.com/docs)\n- [Paystack API Reference](https://paystack.com/docs/api)\n- [Test Cards and Accounts](https://paystack.com/docs/payments/test-payments)\n- [Webhook Event Reference](https://paystack.com/docs/payments/webhooks)","published_title":"Paystack","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"2fc6ea44-a9a6-439d-a7d3-50b59b062a57","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"PayPal","slug":"paypal","content":"## Overview\n\nPayPal is one of the most widely-used payment processors worldwide, supporting credit cards, debit cards, and PayPal account payments. Integrating PayPal into your Emergent app enables you to accept payments from customers in over 200 markets and 25+ currencies.\n\nThis guide walks you through setting up PayPal for your Emergent project, from creating a developer account to processing your first transaction.\n\n<Note>\nPayPal offers both **Standard** (redirect-based) and **Advanced** (in-context checkout) integrations. Emergent supports both patterns - describe your preferred checkout flow in chat and the platform will set up the appropriate implementation.\n</Note>\n\n## Before you begin\n\nYou'll need:\n\n- A PayPal Business account (or a PayPal Developer sandbox account for testing)\n- Your app published or running on your cloud preview ({slug}.preview.emergentagent.com) or published app in Emergent\n- Basic understanding of your app's payment flow\n\n<Tip>\nIf you don't have a PayPal Business account yet, you can start with a free Developer account at [developer.paypal.com](https://developer.paypal.com) - it includes sandbox credentials for testing without processing real money.\n</Tip>\n\n## Get your PayPal API credentials\n\n## Part 1: PayPal Sandbox Setup (Testing)\n\n<Steps>\n<Step title=\"Describe your payment flow\">\nTell Emergent what you want to build with PayPal and where you want payments to happen in your app.\n\nFor example:\n\n> \"Add PayPal checkout to the pricing page and allow users to complete payments.\"\n\nThe agent will use this information to set up the appropriate PayPal checkout flow.\n</Step>\n\n<Step title=\"Log in to PayPal Developer\">\nGo to [PayPal Developer](https://developer.paypal.com/?utm_source=chatgpt.com) and log in with your PayPal account.\n</Step>\n\n<Step title=\"Open Apps & Credentials\">\nIn the PayPal Developer Dashboard, go to **Apps & Credentials** and select the **Sandbox** toggle. Sandbox credentials are used to test payments without processing real transactions.\n</Step>\n\n<Step title=\"Open or create an app\">\nOpen the **Default App**, or click **Create App** and enter an app name, such as `MiniStore`.\n\nPayPal will create an app that you can use to connect your application to the PayPal Sandbox.\n</Step>\n\n<Step title=\"Copy your credentials\">\nOpen the app and copy the **Client ID** and **Secret**.\n\nThese credentials allow your application to authenticate with PayPal's API in the Sandbox environment.\n</Step>\n\n<Step title=\"Connect to Emergent\">\nWhen Emergent asks for your PayPal credentials, provide the **Client ID** and **Secret**.\n\nThe agent will securely configure the credentials and wire the PayPal integration into your app.\n</Step>\n\n<Step title=\"Test the payment flow\">\nOnce the integration is implemented, test the checkout flow using the PayPal Sandbox.\n\nConfirm that users can start checkout, complete the payment, and that your application correctly handles the payment result.\n</Step>\n</Steps>\n\n## Part 2: Go Live (Real Payments)\n\n<Steps>\n<Step title=\"Create or verify a PayPal Business account\">\nGo to [PayPal Business](https://www.paypal.com/in/home?utm_source=chatgpt.com) and create or use your **Business account**.\n\nComplete any required verification before accepting real payments.\n</Step>\n\n<Step title=\"Open Apps & Credentials\">\nGo to [PayPal Developer](https://developer.paypal.com/?utm_source=chatgpt.com) → **Apps & Credentials** and switch from **Sandbox** to **Live**.\n\nThe Live environment uses separate credentials from your Sandbox application.\n</Step>\n\n<Step title=\"Open or create your Live app\">\nOpen your existing Live app, or click **Create App** if you need to create one.\n</Step>\n\n<Step title=\"Copy Live credentials\">\nOpen the Live app and copy the **Live Client ID** and **Live Secret**.\n\nThese credentials will be used for processing real PayPal payments.\n</Step>\n\n<Step title=\"Update Emergent\">\nAfter the first publish, replace the Sandbox configuration with the Live configuration in the **Emergent Secret Panel**:\n\n- **Client ID** → Live Client ID\n- **Secret** → Live Secret\n\nThen re-publish the app.\n</Step>\n\n<Step title=\"Verify the live payment flow\">\nAfter publish, complete a real payment to confirm that the Live PayPal integration is working correctly.\n</Step>\n</Steps>","order":60,"parent_id":null,"icon":"tag","description":"PayPal","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.878778+00:00","published_at":"2026-09-22T06:19:16.878778+00:00","published_content":"## Overview\n\nPayPal is one of the most widely-used payment processors worldwide, supporting credit cards, debit cards, and PayPal account payments. Integrating PayPal into your Emergent app enables you to accept payments from customers in over 200 markets and 25+ currencies.\n\nThis guide walks you through setting up PayPal for your Emergent project, from creating a developer account to processing your first transaction.\n\n<Note>\nPayPal offers both **Standard** (redirect-based) and **Advanced** (in-context checkout) integrations. Emergent supports both patterns - describe your preferred checkout flow in chat and the platform will set up the appropriate implementation.\n</Note>\n\n## Before you begin\n\nYou'll need:\n\n- A PayPal Business account (or a PayPal Developer sandbox account for testing)\n- Your app published or running on your cloud preview ({slug}.preview.emergentagent.com) or published app in Emergent\n- Basic understanding of your app's payment flow\n\n<Tip>\nIf you don't have a PayPal Business account yet, you can start with a free Developer account at [developer.paypal.com](https://developer.paypal.com) - it includes sandbox credentials for testing without processing real money.\n</Tip>\n\n## Get your PayPal API credentials\n\n## Part 1: PayPal Sandbox Setup (Testing)\n\n<Steps>\n<Step title=\"Describe your payment flow\">\nTell Emergent what you want to build with PayPal and where you want payments to happen in your app.\n\nFor example:\n\n> \"Add PayPal checkout to the pricing page and allow users to complete payments.\"\n\nThe agent will use this information to set up the appropriate PayPal checkout flow.\n</Step>\n\n<Step title=\"Log in to PayPal Developer\">\nGo to [PayPal Developer](https://developer.paypal.com/?utm_source=chatgpt.com) and log in with your PayPal account.\n</Step>\n\n<Step title=\"Open Apps & Credentials\">\nIn the PayPal Developer Dashboard, go to **Apps & Credentials** and select the **Sandbox** toggle. Sandbox credentials are used to test payments without processing real transactions.\n</Step>\n\n<Step title=\"Open or create an app\">\nOpen the **Default App**, or click **Create App** and enter an app name, such as `MiniStore`.\n\nPayPal will create an app that you can use to connect your application to the PayPal Sandbox.\n</Step>\n\n<Step title=\"Copy your credentials\">\nOpen the app and copy the **Client ID** and **Secret**.\n\nThese credentials allow your application to authenticate with PayPal's API in the Sandbox environment.\n</Step>\n\n<Step title=\"Connect to Emergent\">\nWhen Emergent asks for your PayPal credentials, provide the **Client ID** and **Secret**.\n\nThe agent will securely configure the credentials and wire the PayPal integration into your app.\n</Step>\n\n<Step title=\"Test the payment flow\">\nOnce the integration is implemented, test the checkout flow using the PayPal Sandbox.\n\nConfirm that users can start checkout, complete the payment, and that your application correctly handles the payment result.\n</Step>\n</Steps>\n\n## Part 2: Go Live (Real Payments)\n\n<Steps>\n<Step title=\"Create or verify a PayPal Business account\">\nGo to [PayPal Business](https://www.paypal.com/in/home?utm_source=chatgpt.com) and create or use your **Business account**.\n\nComplete any required verification before accepting real payments.\n</Step>\n\n<Step title=\"Open Apps & Credentials\">\nGo to [PayPal Developer](https://developer.paypal.com/?utm_source=chatgpt.com) → **Apps & Credentials** and switch from **Sandbox** to **Live**.\n\nThe Live environment uses separate credentials from your Sandbox application.\n</Step>\n\n<Step title=\"Open or create your Live app\">\nOpen your existing Live app, or click **Create App** if you need to create one.\n</Step>\n\n<Step title=\"Copy Live credentials\">\nOpen the Live app and copy the **Live Client ID** and **Live Secret**.\n\nThese credentials will be used for processing real PayPal payments.\n</Step>\n\n<Step title=\"Update Emergent\">\nAfter the first publish, replace the Sandbox configuration with the Live configuration in the **Emergent Secret Panel**:\n\n- **Client ID** → Live Client ID\n- **Secret** → Live Secret\n\nThen re-publish the app.\n</Step>\n\n<Step title=\"Verify the live payment flow\">\nAfter publish, complete a real payment to confirm that the Live PayPal integration is working correctly.\n</Step>\n</Steps>","published_title":"PayPal","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"37efdab3-8001-4797-82ab-8aebfa616b4a","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Emergent Auth (built-in)","slug":"emergent-auth-built-in","content":"## What is Emergent Auth?\n\nEmergent Auth is the platform's built-in authentication and user-management system. Every app created on Emergent automatically includes authentication capabilities - no third-party service or complex configuration required.\n\nWhen you describe user sign-up, login, or access control in your chat prompt, the AI agents wire up Emergent Auth behind the scenes. User credentials, sessions, and profile data are stored securely within your app's environment.\n\n<Note>\nEmergent Auth is included at no additional cost. You don't need API keys, OAuth apps, or separate billing for auth providers.\n</Note>\n\n## How it works\n\nEmergent Auth provides:\n\n- **Google sign-in** - users can sign in with their Google account (no Google Cloud credentials required for basic use; supply `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` only if you need custom consent-screen branding or extra scopes such as Gmail/Calendar).\n- **Email and password login** - users sign up and log in with an email and password.\n\nLogin runs on the hosted **auth.emergentagent.com** page. The \"Secured by Emergent\" branding is present on this page and cannot be removed on any tier.\n\nThe underlying user data lives in your app's [MongoDB database](/database-mongodb), so you can query and extend it just like any other collection.\n\n## Typical usage in prompts\n\nYou interact with authentication by describing what you want in natural language. For example:\n\n- _\"Users should be able to sign up with email and password, then log in to see their dashboard.\"_\n- _\"Add a login page. Only logged-in users can create posts.\"_\n- _\"Add Google sign-in.\"_\n\nThe agents will generate login and sign-up UI, wire up backend endpoints, enforce route protection, and handle sessions - all using Emergent Auth.\n\n## Security best practices\n\nEmergent Auth follows industry-standard security practices out of the box:\n\n- Passwords are **never stored in plaintext**; they are hashed using bcrypt or Argon2.\n- Sessions use **secure, HTTP-only cookies** with `SameSite` and `Secure` flags in production.\n- Rate limiting is applied to login and sign-up endpoints to mitigate brute-force attacks.\n- HTTPS is enforced for all production apps.\n\n<Tip>\nIf your app handles sensitive data (health, finance, etc.), describe additional requirements in your prompt - e.g., _\"Require two-factor authentication\"_ or _\"Log all login attempts.\"_ The agents will implement these features.\n</Tip>\n\n## Switching to a third-party auth provider\n\nIf you later decide to migrate to an external provider (e.g., Clerk, Supabase Auth, Auth0), you can instruct the agents to refactor your app:\n\n- _\"Replace Emergent Auth with Clerk for authentication.\"_\n\nThe agents will update routes, remove the built-in session logic, and integrate the new provider's SDK. User data migration may require additional steps depending on the provider.\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\n    Learn how user data is stored and queried in your app's MongoDB instance.\n</Card>\n</CardGroup>","order":66,"parent_id":null,"icon":"lock","description":"Emergent Auth (built-in)","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.881849+00:00","published_at":"2026-09-22T06:19:16.881849+00:00","published_content":"## What is Emergent Auth?\n\nEmergent Auth is the platform's built-in authentication and user-management system. Every app created on Emergent automatically includes authentication capabilities - no third-party service or complex configuration required.\n\nWhen you describe user sign-up, login, or access control in your chat prompt, the AI agents wire up Emergent Auth behind the scenes. User credentials, sessions, and profile data are stored securely within your app's environment.\n\n<Note>\nEmergent Auth is included at no additional cost. You don't need API keys, OAuth apps, or separate billing for auth providers.\n</Note>\n\n## How it works\n\nEmergent Auth provides:\n\n- **Google sign-in** - users can sign in with their Google account (no Google Cloud credentials required for basic use; supply `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` only if you need custom consent-screen branding or extra scopes such as Gmail/Calendar).\n- **Email and password login** - users sign up and log in with an email and password.\n\nLogin runs on the hosted **auth.emergentagent.com** page. The \"Secured by Emergent\" branding is present on this page and cannot be removed on any tier.\n\nThe underlying user data lives in your app's [MongoDB database](/database-mongodb), so you can query and extend it just like any other collection.\n\n## Typical usage in prompts\n\nYou interact with authentication by describing what you want in natural language. For example:\n\n- _\"Users should be able to sign up with email and password, then log in to see their dashboard.\"_\n- _\"Add a login page. Only logged-in users can create posts.\"_\n- _\"Add Google sign-in.\"_\n\nThe agents will generate login and sign-up UI, wire up backend endpoints, enforce route protection, and handle sessions - all using Emergent Auth.\n\n## Security best practices\n\nEmergent Auth follows industry-standard security practices out of the box:\n\n- Passwords are **never stored in plaintext**; they are hashed using bcrypt or Argon2.\n- Sessions use **secure, HTTP-only cookies** with `SameSite` and `Secure` flags in production.\n- Rate limiting is applied to login and sign-up endpoints to mitigate brute-force attacks.\n- HTTPS is enforced for all production apps.\n\n<Tip>\nIf your app handles sensitive data (health, finance, etc.), describe additional requirements in your prompt - e.g., _\"Require two-factor authentication\"_ or _\"Log all login attempts.\"_ The agents will implement these features.\n</Tip>\n\n## Switching to a third-party auth provider\n\nIf you later decide to migrate to an external provider (e.g., Clerk, Supabase Auth, Auth0), you can instruct the agents to refactor your app:\n\n- _\"Replace Emergent Auth with Clerk for authentication.\"_\n\nThe agents will update routes, remove the built-in session logic, and integrate the new provider's SDK. User data migration may require additional steps depending on the provider.\n\n## Related pages\n\n<CardGroup cols={2}>\n<Card title=\"Database (MongoDB)\" icon=\"database\" href=\"/database-mongodb\">\n    Learn how user data is stored and queried in your app's MongoDB instance.\n</Card>\n</CardGroup>","published_title":"Emergent Auth (built-in)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"34c98de6-fd8d-440e-91a9-ec1d3e83953f","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"OpenAI","slug":"openai","content":"## Overview\n\nOpenAI provides industry-leading language models including GPT-6 and the GPT-5.x family. Emergent supports OpenAI models out of the box, allowing you to build applications powered by these models through simple chat interactions.\n\nYou can use OpenAI models in two ways:\n\n- **Automatically** via [The Universal LLM Key](/the-universal-llm-key) - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your OpenAI account for direct billing and usage tracking\n\n## Using OpenAI with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to OpenAI models without any configuration.\n\n<Note>\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including OpenAI. Your usage is metered as part of your Emergent subscription.\n</Note>\n\nWhen you describe your app in chat, Emergent agents automatically use OpenAI models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n## Connecting Your Own OpenAI API Key\n\nThe preferred approach is the Universal LLM Key . However, if you want to bring your own OpenAI API key, you can provide your own key when Emergent asks for your OpenAI credentials.\n\nVisit [platform.openai.com/api-keys](https://platform.openai.com/api-keys) and sign in to your OpenAI account. Click **Create new secret key**, give it a descriptive name, and copy the key immediately (it won't be shown again).\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n## Building AI Features with OpenAI\n\nWhen describing your app in chat, you can reference OpenAI capabilities directly:\n\nSimply describe what you want in natural language:\n\n_\"Add a chatbot that uses GPT-5.4 to answer customer questions about our products\"_\n\n_\"Create a content summarizer using GPT-5.x\"_\n\n_\"Build an AI writing assistant with GPT-6 for generating blog posts\"_\n\nEmergent agents will generate the appropriate code to integrate OpenAI models. Your application will include properly structured API calls with error handling, streaming support, and token management.\n\nThe generated code handles:\n\n- Authentication and API key management\n- Request formatting and model parameters\n- Response parsing and streaming\n- Rate limiting and error recovery\n\n## Best Practices\n\n<CardGroup cols={2}>\n<Card title=\"Choose the right model\">\nUse more capable models in the GPT-6 / GPT-5.x lineup for complex reasoning and creativity. Use lighter models for speed and cost efficiency on simpler tasks.\n</Card>\n\n<Card title=\"Monitor usage\">\nTrack your OpenAI API usage in the OpenAI dashboard to manage costs. Set usage limits if needed.\n</Card>\n\n<Card title=\"Implement caching\">\nFor repeated queries, describe caching requirements to Emergent agents to reduce API calls and costs.\n</Card>\n\n<Card title=\"Handle rate limits\">\nDescribe retry logic and graceful degradation when explaining features that make frequent API calls.\n</Card>\n</CardGroup>\n\n## Cost Optimization\n\nWhen building AI-powered features, consider these strategies to optimize OpenAI costs:\n\n- **Use appropriate models** - Match model capability to task complexity\n- **Implement prompt caching** - Cache responses for identical or similar queries\n- **Limit context length** - Only include necessary context in prompts\n- **Use streaming** - Stream responses for better user experience without extra cost\n- **Set max tokens** - Configure maximum response lengths to prevent runaway costs\n\n<Tip>\nWhen describing AI features to Emergent, mention cost optimization requirements explicitly: _\"Build this feature to minimize token usage\"_ or _\"Use a cost-efficient model for this task\"_.\n</Tip>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| API key not working or showing authentication errors | Verify that: - Your API key was copied correctly without extra spaces - Your OpenAI account has billing enabled and sufficient credits - The API key has not been revoked in your OpenAI dashboard - You've saved the configuration in Emergent after pasting the key |\n| Rate limit errors | OpenAI enforces rate limits based on your account tier. If you encounter rate limit errors: - Implement exponential backoff and retry logic (describe this to Emergent agents) - Upgrade your OpenAI account tier for higher limits - Reduce request frequency in your application logic |\n| High costs or unexpected billing | Review your OpenAI usage dashboard to identify expensive operations: - Check if prompts are longer than necessary - Verify you're using the intended model - Look for API calls in loops or high-frequency events - Set up usage alerts in your OpenAI account |\n| Model not available or deprecated warnings | OpenAI occasionally deprecates older models. If you see deprecation warnings: - Update your model configuration to use current model versions - Describe the required change to Emergent agents: _\"Update to use the latest GPT-5.x model\"_ - Test thoroughly after model changes as behavior may differ slightly |\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nLearn about Emergent's built-in AI access across multiple providers\n</Card>\n\n<Card title=\"Glossary of Emergent Terms\" href=\"/glossary-of-emergent-terms\">\nUnderstand key concepts and terminology used in Emergent\n</Card>\n</CardGroup>","order":70,"parent_id":null,"icon":"sparkles","description":"OpenAI","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.862313+00:00","published_at":"2026-09-22T06:19:16.862313+00:00","published_content":"## Overview\n\nOpenAI provides industry-leading language models including GPT-6 and the GPT-5.x family. Emergent supports OpenAI models out of the box, allowing you to build applications powered by these models through simple chat interactions.\n\nYou can use OpenAI models in two ways:\n\n- **Automatically** via [The Universal LLM Key](/the-universal-llm-key) - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your OpenAI account for direct billing and usage tracking\n\n## Using OpenAI with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to OpenAI models without any configuration.\n\n<Note>\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including OpenAI. Your usage is metered as part of your Emergent subscription.\n</Note>\n\nWhen you describe your app in chat, Emergent agents automatically use OpenAI models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n## Connecting Your Own OpenAI API Key\n\nThe preferred approach is the Universal LLM Key . However, if you want to bring your own OpenAI API key, you can provide your own key when Emergent asks for your OpenAI credentials.\n\nVisit [platform.openai.com/api-keys](https://platform.openai.com/api-keys) and sign in to your OpenAI account. Click **Create new secret key**, give it a descriptive name, and copy the key immediately (it won't be shown again).\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n## Building AI Features with OpenAI\n\nWhen describing your app in chat, you can reference OpenAI capabilities directly:\n\nSimply describe what you want in natural language:\n\n_\"Add a chatbot that uses GPT-5.4 to answer customer questions about our products\"_\n\n_\"Create a content summarizer using GPT-5.x\"_\n\n_\"Build an AI writing assistant with GPT-6 for generating blog posts\"_\n\nEmergent agents will generate the appropriate code to integrate OpenAI models. Your application will include properly structured API calls with error handling, streaming support, and token management.\n\nThe generated code handles:\n\n- Authentication and API key management\n- Request formatting and model parameters\n- Response parsing and streaming\n- Rate limiting and error recovery\n\n## Best Practices\n\n<CardGroup cols={2}>\n<Card title=\"Choose the right model\">\nUse more capable models in the GPT-6 / GPT-5.x lineup for complex reasoning and creativity. Use lighter models for speed and cost efficiency on simpler tasks.\n</Card>\n\n<Card title=\"Monitor usage\">\nTrack your OpenAI API usage in the OpenAI dashboard to manage costs. Set usage limits if needed.\n</Card>\n\n<Card title=\"Implement caching\">\nFor repeated queries, describe caching requirements to Emergent agents to reduce API calls and costs.\n</Card>\n\n<Card title=\"Handle rate limits\">\nDescribe retry logic and graceful degradation when explaining features that make frequent API calls.\n</Card>\n</CardGroup>\n\n## Cost Optimization\n\nWhen building AI-powered features, consider these strategies to optimize OpenAI costs:\n\n- **Use appropriate models** - Match model capability to task complexity\n- **Implement prompt caching** - Cache responses for identical or similar queries\n- **Limit context length** - Only include necessary context in prompts\n- **Use streaming** - Stream responses for better user experience without extra cost\n- **Set max tokens** - Configure maximum response lengths to prevent runaway costs\n\n<Tip>\nWhen describing AI features to Emergent, mention cost optimization requirements explicitly: _\"Build this feature to minimize token usage\"_ or _\"Use a cost-efficient model for this task\"_.\n</Tip>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| API key not working or showing authentication errors | Verify that: - Your API key was copied correctly without extra spaces - Your OpenAI account has billing enabled and sufficient credits - The API key has not been revoked in your OpenAI dashboard - You've saved the configuration in Emergent after pasting the key |\n| Rate limit errors | OpenAI enforces rate limits based on your account tier. If you encounter rate limit errors: - Implement exponential backoff and retry logic (describe this to Emergent agents) - Upgrade your OpenAI account tier for higher limits - Reduce request frequency in your application logic |\n| High costs or unexpected billing | Review your OpenAI usage dashboard to identify expensive operations: - Check if prompts are longer than necessary - Verify you're using the intended model - Look for API calls in loops or high-frequency events - Set up usage alerts in your OpenAI account |\n| Model not available or deprecated warnings | OpenAI occasionally deprecates older models. If you see deprecation warnings: - Update your model configuration to use current model versions - Describe the required change to Emergent agents: _\"Update to use the latest GPT-5.x model\"_ - Test thoroughly after model changes as behavior may differ slightly |\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nLearn about Emergent's built-in AI access across multiple providers\n</Card>\n\n<Card title=\"Glossary of Emergent Terms\" href=\"/glossary-of-emergent-terms\">\nUnderstand key concepts and terminology used in Emergent\n</Card>\n</CardGroup>","published_title":"OpenAI","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"dd4fd01f-4216-4efc-9b2a-adf7ad91fdcc","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Claude","slug":"claude","content":"## Overview\n\nClaude is Anthropic's family of large language models known for extended context windows, strong reasoning capabilities, and careful instruction-following. Emergent natively supports Claude models through the **Universal LLM Key**, allowing you to use Claude for code generation, chat interactions, and other AI-powered features throughout the platform.\n\nYou can use Claude models in two ways:\n\n- **Automatically** via the **Universal LLM Key** - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your Anthropic account for direct billing and usage tracking\n\n## Using Claude with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to Claude models without any configuration.\n\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including Anthropic. Your usage is metered as part of your Emergent subscription.\n\nWhen you describe your app in chat, Emergent agents automatically use Claude models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n## Connecting Your Own Claude API Key\n\nThe preferred approach is the **Universal LLM Key**. However, if you want to bring your own Claude API key, you can provide your own key when Emergent asks for your Claude credentials.\n\nVisit [console.anthropic.com](http://console.anthropic.com) and sign in to your Anthropic account. Create an API key and copy it.\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Claude responses are slower than expected | Larger models (Opus, Sonnet) prioritize quality over speed. If you need faster iteration, try **Claude Haiku 4.5** for simpler tasks, then switch back to Sonnet for final polish. |\n| Model returns 'overloaded' errors | Anthropic's API occasionally experiences high demand. Emergent will automatically retry. You can also manually retry the message or switch to another model temporarily. |\n| Unexpected refusals or overly cautious responses | Claude is trained to decline potentially unsafe requests. If you believe a refusal is incorrect, rephrase your prompt to clarify intent, or try a different model for comparison. |\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nManage credits, view usage, and top up your balance\n</Card>\n<Card title=\"Glossary\" href=\"/glossary-of-emergent-terms\">\nLearn platform-specific terms like agents, conversations, and published versions\n</Card>\n</CardGroup>","order":71,"parent_id":null,"icon":"sparkles","description":"Claude","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.855492+00:00","published_at":"2026-09-22T06:19:16.855492+00:00","published_content":"## Overview\n\nClaude is Anthropic's family of large language models known for extended context windows, strong reasoning capabilities, and careful instruction-following. Emergent natively supports Claude models through the **Universal LLM Key**, allowing you to use Claude for code generation, chat interactions, and other AI-powered features throughout the platform.\n\nYou can use Claude models in two ways:\n\n- **Automatically** via the **Universal LLM Key** - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your Anthropic account for direct billing and usage tracking\n\n## Using Claude with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to Claude models without any configuration.\n\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including Anthropic. Your usage is metered as part of your Emergent subscription.\n\nWhen you describe your app in chat, Emergent agents automatically use Claude models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n## Connecting Your Own Claude API Key\n\nThe preferred approach is the **Universal LLM Key**. However, if you want to bring your own Claude API key, you can provide your own key when Emergent asks for your Claude credentials.\n\nVisit [console.anthropic.com](http://console.anthropic.com) and sign in to your Anthropic account. Create an API key and copy it.\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| Claude responses are slower than expected | Larger models (Opus, Sonnet) prioritize quality over speed. If you need faster iteration, try **Claude Haiku 4.5** for simpler tasks, then switch back to Sonnet for final polish. |\n| Model returns 'overloaded' errors | Anthropic's API occasionally experiences high demand. Emergent will automatically retry. You can also manually retry the message or switch to another model temporarily. |\n| Unexpected refusals or overly cautious responses | Claude is trained to decline potentially unsafe requests. If you believe a refusal is incorrect, rephrase your prompt to clarify intent, or try a different model for comparison. |\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nManage credits, view usage, and top up your balance\n</Card>\n<Card title=\"Glossary\" href=\"/glossary-of-emergent-terms\">\nLearn platform-specific terms like agents, conversations, and published versions\n</Card>\n</CardGroup>","published_title":"Claude","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"5ffcbdeb-aa51-4408-9f57-d55d7a7243f5","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Gemini","slug":"gemini","content":"## Overview\n\nGoogle Gemini is a family of multimodal AI models that can be integrated into your Emergent applications for chat, content generation, vision tasks, and more. Emergent provides built-in support for Gemini models through the Universal LLM Key system, making it simple to add Google's latest AI capabilities to your app.\n\nThis guide walks you through setting up Gemini in your Emergent project and making your first API call.\n\n---\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- An active Emergent project\n\n<Note>\nGemini access is Emergent-managed, you do not need a Google Cloud account or a Gemini API key to get started. Bringing your own key is optional.\n</Note>\n\nYou can use Gemini models in two ways:\n\n- **Automatically** via the **Universal LLM Key** - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your Google account for direct billing and usage tracking\n\n---\n\n## Using Gemini with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to Gemini models without any configuration.\n\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including Google. Your usage is metered as part of your Emergent subscription.\n\nWhen you describe your app in chat, Emergent agents automatically use Gemini models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n---\n\n## Connecting Your Own Gemini API Key\n\nThe preferred approach is the **Universal LLM Key**. However, if you want to bring your own Gemini API key, you can provide your own key when Emergent asks for your Gemini credentials.\n\nVisit [Google AI Studio](https://aistudio.google.com/apikey) and sign in to your Google account. Create an API key and copy it.\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n---\n\n## Multimodal Capabilities\n\nGemini models support text, image, audio, and video inputs, making them ideal for applications that need to process multiple content types.\n\n### Example: Vision Task\n\n_(The agent writes and wires up this code for you.)_\n\n---\n\n## Troubleshooting\n\n<Warning>\nIf you are using your own key and see authentication errors, verify that your `GOOGLE_API_KEY` is correctly set and that the key has not been revoked or restricted in the Google Cloud Console.\n</Warning>\n\nCommon issues and solutions:\n\n| Issue | Solution |\n| --- | --- |\n| **\"API key not valid\"** | Double-check that you copied the full key without extra spaces. Regenerate the key in Google AI Studio if needed. |\n| **\"Model not found\"** | Ensure you're using a valid model identifier (e.g., `gemini-2.5-flash`). Some models may require allowlist access. |\n| **Slow responses** | Gemini Pro models may take longer for complex requests. Consider using Flash models for latency-sensitive applications. |\n| **CORS errors** | Gemini API calls should be made server-side. If calling from the browser, proxy requests through your Emergent backend. |\n\n---\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nLearn how Emergent manages AI provider credentials securely\n</Card>\n\n<Card title=\"Glossary\" href=\"/glossary-of-emergent-terms\">\nUnderstand key terms used throughout the platform\n</Card>\n</CardGroup>","order":72,"parent_id":null,"icon":"sparkles","description":"Gemini","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.887234+00:00","published_at":"2026-09-22T06:19:16.887234+00:00","published_content":"## Overview\n\nGoogle Gemini is a family of multimodal AI models that can be integrated into your Emergent applications for chat, content generation, vision tasks, and more. Emergent provides built-in support for Gemini models through the Universal LLM Key system, making it simple to add Google's latest AI capabilities to your app.\n\nThis guide walks you through setting up Gemini in your Emergent project and making your first API call.\n\n---\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- An active Emergent project\n\n<Note>\nGemini access is Emergent-managed, you do not need a Google Cloud account or a Gemini API key to get started. Bringing your own key is optional.\n</Note>\n\nYou can use Gemini models in two ways:\n\n- **Automatically** via the **Universal LLM Key** - Emergent provides access without requiring your own API key\n- **With your own API key** - Connect your Google account for direct billing and usage tracking\n\n---\n\n## Using Gemini with the Universal LLM Key\n\nThe simplest way to get started is using Emergent's Universal LLM Key, which provides immediate access to Gemini models without any configuration.\n\nThe Universal LLM Key is included with your Emergent account and supports multiple AI providers including Google. Your usage is metered as part of your Emergent subscription.\n\nWhen you describe your app in chat, Emergent agents automatically use Gemini models (or other supported providers) through the Universal LLM Key. No additional setup is required - just start building.\n\n---\n\n## Connecting Your Own Gemini API Key\n\nThe preferred approach is the **Universal LLM Key**. However, if you want to bring your own Gemini API key, you can provide your own key when Emergent asks for your Gemini credentials.\n\nVisit [Google AI Studio](https://aistudio.google.com/apikey) and sign in to your Google account. Create an API key and copy it.\n\n<Warning>\nNever commit your API key to version control or share it publicly. Treat it like a password.\n</Warning>\n\n---\n\n## Multimodal Capabilities\n\nGemini models support text, image, audio, and video inputs, making them ideal for applications that need to process multiple content types.\n\n### Example: Vision Task\n\n_(The agent writes and wires up this code for you.)_\n\n---\n\n## Troubleshooting\n\n<Warning>\nIf you are using your own key and see authentication errors, verify that your `GOOGLE_API_KEY` is correctly set and that the key has not been revoked or restricted in the Google Cloud Console.\n</Warning>\n\nCommon issues and solutions:\n\n| Issue | Solution |\n| --- | --- |\n| **\"API key not valid\"** | Double-check that you copied the full key without extra spaces. Regenerate the key in Google AI Studio if needed. |\n| **\"Model not found\"** | Ensure you're using a valid model identifier (e.g., `gemini-2.5-flash`). Some models may require allowlist access. |\n| **Slow responses** | Gemini Pro models may take longer for complex requests. Consider using Flash models for latency-sensitive applications. |\n| **CORS errors** | Gemini API calls should be made server-side. If calling from the browser, proxy requests through your Emergent backend. |\n\n---\n\n## Related Resources\n\n<CardGroup cols={2}>\n<Card title=\"The Universal LLM Key\" href=\"/the-universal-llm-key\">\nLearn how Emergent manages AI provider credentials securely\n</Card>\n\n<Card title=\"Glossary\" href=\"/glossary-of-emergent-terms\">\nUnderstand key terms used throughout the platform\n</Card>\n</CardGroup>","published_title":"Gemini","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"0f10408a-4ff1-43c2-a02c-a7635cfeaf9d","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Twilio","slug":"twilio","content":"## Overview\n\nTwilio is a cloud communications platform that enables your Emergent app to send SMS messages, make voice calls, and deliver notifications. This integration is ideal for apps that need to verify users via SMS, send transactional alerts, or implement two-factor authentication.\n\n<Note>\nTwilio charges per message or call. Review [Twilio's pricing](https://www.twilio.com/pricing) before implementing SMS or voice features at scale.\n</Note>\n\n## Prerequisites\n\nBefore integrating Twilio, you'll need:\n\n- A Twilio account ([sign up here](https://www.twilio.com/try-twilio))\n- A Twilio phone number (purchased from your Twilio console)\n- Your Twilio Account SID and Auth Token (found in your Twilio console dashboard)\n\n## Setting up Twilio in Emergent\n\n<Steps>\n<Step title=\"Describe your SMS or voice feature\">\nTell Emergent what you want to build with Twilio. For example:\n\n- _\"Add SMS verification when users sign up - send a 6-digit code to their phone number.\"_\n- _\"Send an SMS notification when an order ships, including the tracking number.\"_\n- _\"Let users opt in to receive weekly SMS reminders about their appointments.\"_\n</Step>\n\n<Step title=\"Obtain your Twilio credentials\">\nLog in to your [Twilio Console](https://console.twilio.com/?utm_source=chatgpt.com) and locate your **Account SID** and **Auth Token** on the dashboard.\n\nIf you haven't already, purchase a phone number from **Phone Numbers → Buy a Number**. This number will be the sender for your SMS messages.\n</Step>\n\n<Step title=\"Provide your credentials to Emergent\">\nWhen Emergent asks, provide your **Account SID**, **Auth Token**, and **Twilio phone number**. The agent will securely configure and wire them into your app.\n</Step>\n\n<Step title=\"Implement and test the integration\">\nThe agent will set up the required Twilio API calls and publish the changes. Test the SMS or voice functionality and check the Twilio Console logs to verify delivery.\n</Step>\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"Phone verification\" icon=\"shield-check\">\nSend a one-time passcode via SMS during signup or login to verify a user's phone number.\n</Card>\n\n<Card title=\"Transactional alerts\" icon=\"bell\">\nNotify users of important events - order confirmations, appointment reminders.\n</Card>\n\n<Card title=\"Two-factor authentication\" icon=\"lock\">\nEnhance security by requiring an SMS code in addition to a password when users log in.\n</Card>\n\n<Card title=\"Marketing campaigns\" icon=\"megaphone\">\nSend promotional messages to opted-in users. Ensure compliance with local regulations (e.g., TCPA, GDPR).\n</Card>\n</CardGroup>\n\n## Example implementation\n\nBelow is an example of how Emergent agents might implement an SMS verification flow using Twilio's Node.js SDK:\n\n_(The agent writes and wires up this code for you.)_\n\n_(The agent writes and wires up this code for you.)_\n\n<Info>\nPhone numbers must be in E.164 format (e.g., `+14155552671`). Emergent agents typically validate and format numbers automatically when you describe your feature requirements.\n</Info>\n\n## Testing and debugging\n\n| Issue | Solution |\n| --- | --- |\n| Messages aren't being delivered | Verify your phone number is in E.164 format with a country code (e.g., `+1` for US). Check Twilio's console under **Logs → Messaging** for error codes. Ensure your Twilio account is not in trial mode or has sufficient credit balance. Confirm the recipient's carrier isn't blocking messages (some carriers filter shortcodes or toll-free numbers). |\n| Environment variables not loading | If your app can't read `TWILIO_ACCOUNT_SID` or other variables, ask the agents: _\"Verify my Twilio environment variables are set correctly.\"_ The agents will check your configuration and re-publish if needed. |\n| Rate limiting or throttling errors | Twilio enforces rate limits on message sending. If you're sending high volumes, consider: Queueing messages with a background job processor. Requesting a rate limit increase from Twilio support. Using Twilio's Messaging Services for better throughput. |\n\n## Best practices\n\n- **Validate phone numbers** before sending to avoid wasted credits on invalid destinations.\n- **Respect opt-outs**: Honor unsubscribe requests immediately and maintain a suppression list.\n- **Use short, clear messages**: SMS has a 160-character limit (longer messages are split and billed per segment).\n- **Monitor delivery status**: Use Twilio webhooks to track delivery, failures, and user replies.\n- **Secure your credentials**: Never commit `TWILIO_AUTH_TOKEN` to version control. Emergent stores environment variables securely for you.\n\n## Compliance and regulations\n\n<Warning>\nSMS marketing is subject to legal restrictions in many countries. In the US, you must obtain explicit consent before sending promotional messages (TCPA). In the EU, GDPR requires clear consent and easy opt-out mechanisms.\n\nAlways consult legal counsel if you're sending marketing or promotional messages.\n</Warning>","order":74,"parent_id":null,"icon":"mail","description":"Twilio","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.884826+00:00","published_at":"2026-09-22T06:19:16.884826+00:00","published_content":"## Overview\n\nTwilio is a cloud communications platform that enables your Emergent app to send SMS messages, make voice calls, and deliver notifications. This integration is ideal for apps that need to verify users via SMS, send transactional alerts, or implement two-factor authentication.\n\n<Note>\nTwilio charges per message or call. Review [Twilio's pricing](https://www.twilio.com/pricing) before implementing SMS or voice features at scale.\n</Note>\n\n## Prerequisites\n\nBefore integrating Twilio, you'll need:\n\n- A Twilio account ([sign up here](https://www.twilio.com/try-twilio))\n- A Twilio phone number (purchased from your Twilio console)\n- Your Twilio Account SID and Auth Token (found in your Twilio console dashboard)\n\n## Setting up Twilio in Emergent\n\n<Steps>\n<Step title=\"Describe your SMS or voice feature\">\nTell Emergent what you want to build with Twilio. For example:\n\n- _\"Add SMS verification when users sign up - send a 6-digit code to their phone number.\"_\n- _\"Send an SMS notification when an order ships, including the tracking number.\"_\n- _\"Let users opt in to receive weekly SMS reminders about their appointments.\"_\n</Step>\n\n<Step title=\"Obtain your Twilio credentials\">\nLog in to your [Twilio Console](https://console.twilio.com/?utm_source=chatgpt.com) and locate your **Account SID** and **Auth Token** on the dashboard.\n\nIf you haven't already, purchase a phone number from **Phone Numbers → Buy a Number**. This number will be the sender for your SMS messages.\n</Step>\n\n<Step title=\"Provide your credentials to Emergent\">\nWhen Emergent asks, provide your **Account SID**, **Auth Token**, and **Twilio phone number**. The agent will securely configure and wire them into your app.\n</Step>\n\n<Step title=\"Implement and test the integration\">\nThe agent will set up the required Twilio API calls and publish the changes. Test the SMS or voice functionality and check the Twilio Console logs to verify delivery.\n</Step>\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"Phone verification\" icon=\"shield-check\">\nSend a one-time passcode via SMS during signup or login to verify a user's phone number.\n</Card>\n\n<Card title=\"Transactional alerts\" icon=\"bell\">\nNotify users of important events - order confirmations, appointment reminders.\n</Card>\n\n<Card title=\"Two-factor authentication\" icon=\"lock\">\nEnhance security by requiring an SMS code in addition to a password when users log in.\n</Card>\n\n<Card title=\"Marketing campaigns\" icon=\"megaphone\">\nSend promotional messages to opted-in users. Ensure compliance with local regulations (e.g., TCPA, GDPR).\n</Card>\n</CardGroup>\n\n## Example implementation\n\nBelow is an example of how Emergent agents might implement an SMS verification flow using Twilio's Node.js SDK:\n\n_(The agent writes and wires up this code for you.)_\n\n_(The agent writes and wires up this code for you.)_\n\n<Info>\nPhone numbers must be in E.164 format (e.g., `+14155552671`). Emergent agents typically validate and format numbers automatically when you describe your feature requirements.\n</Info>\n\n## Testing and debugging\n\n| Issue | Solution |\n| --- | --- |\n| Messages aren't being delivered | Verify your phone number is in E.164 format with a country code (e.g., `+1` for US). Check Twilio's console under **Logs → Messaging** for error codes. Ensure your Twilio account is not in trial mode or has sufficient credit balance. Confirm the recipient's carrier isn't blocking messages (some carriers filter shortcodes or toll-free numbers). |\n| Environment variables not loading | If your app can't read `TWILIO_ACCOUNT_SID` or other variables, ask the agents: _\"Verify my Twilio environment variables are set correctly.\"_ The agents will check your configuration and re-publish if needed. |\n| Rate limiting or throttling errors | Twilio enforces rate limits on message sending. If you're sending high volumes, consider: Queueing messages with a background job processor. Requesting a rate limit increase from Twilio support. Using Twilio's Messaging Services for better throughput. |\n\n## Best practices\n\n- **Validate phone numbers** before sending to avoid wasted credits on invalid destinations.\n- **Respect opt-outs**: Honor unsubscribe requests immediately and maintain a suppression list.\n- **Use short, clear messages**: SMS has a 160-character limit (longer messages are split and billed per segment).\n- **Monitor delivery status**: Use Twilio webhooks to track delivery, failures, and user replies.\n- **Secure your credentials**: Never commit `TWILIO_AUTH_TOKEN` to version control. Emergent stores environment variables securely for you.\n\n## Compliance and regulations\n\n<Warning>\nSMS marketing is subject to legal restrictions in many countries. In the US, you must obtain explicit consent before sending promotional messages (TCPA). In the EU, GDPR requires clear consent and easy opt-out mechanisms.\n\nAlways consult legal counsel if you're sending marketing or promotional messages.\n</Warning>","published_title":"Twilio","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"22f5b07f-7fb4-46df-aed4-308f54109e6d","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Resend","slug":"resend","content":"## Overview\n\nResend is a modern email API that makes it easy to send transactional and marketing emails from your Emergent app. With its developer-friendly interface and reliable delivery, Resend is ideal for password resets, welcome emails, notifications, and more.\n\nThis guide walks you through integrating Resend into your Emergent project so your AI agents can send emails on behalf of your application.\n\n## Using Resend with Emergent\n\nYou can use Resend in two ways:\n\n- **Automatically with Emergent's Universal LLM Key** - recommended.\n- **With your own Resend API key** - if you prefer to use your own Resend account and credentials.\n\n## Using Resend with Universal LLM Key\n\nThe preferred approach is to use Resend through **Emergent's Universal LLM Key**.\n\nDescribe the email functionality you want in your Emergent project, such as:\n\n> \"Send a confirmation email when a user submits the contact form.\"\n\nEmergent will configure Resend and handle the required credentials for your application.\n\nOnce connected, you can specify the email flows you want your application to support, such as password resets, welcome emails, or notifications.\n\n## Connecting Your Own Resend API Key\n\nIf you want to use your own Resend API key, you can provide your key when Emergent asks for your Resend credentials.\n\n<Steps>\n<Step title=\"Log in to Resend\">\nGo to [Resend](https://resend.com/) and log in or create an account.\n</Step>\n\n<Step title=\"Open API Keys\">\nGo directly to the [Resend API Keys page](https://resend.com/api-keys).\n\n**OR**\n\n- Open the Resend dashboard.\n- Go to **API Keys**.\n</Step>\n\n<Step title=\"Create the API Key\">\n- Click **Create API Key**.\n- Give the API key a name so you can identify which app it is for.\n  - Example: `Customer Feedback App`\n- Create the API key.\n</Step>\n\n<Step title=\"Copy the API Key\">\nCopy the complete secret API key immediately.\n\nIt will look like:\n\n`re_...`\n</Step>\n\n<Step title=\"Connect Resend to Emergent\">\n- When Emergent asks for your Resend credentials, provide the **API key**\n- Agent will securely configure the key and connect Resend to your application.\n</Step>\n\n<Step title=\"Verify Your Domain\">\n- For testing, you can start with your available verified sender setup.\n- To send emails to real customers, go to **Domains → Add Domain** in Resend.\n- Enter a domain that you own.\n- Add the DNS records provided by Resend to your domain provider.\n\nOnce connected, test your email flow to confirm that messages are being sent and delivered correctly.\n</Step>\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"User onboarding\">\nWelcome emails, email verification links, and getting-started guides sent automatically when users sign up.\n</Card>\n\n<Card title=\"Transactional alerts\">\nOrder confirmations, shipping updates, payment receipts, and account security notifications.\n</Card>\n\n<Card title=\"Scheduled digests\">\nDaily or weekly summaries, activity reports, and content recommendations sent on a schedule.\n</Card>\n\n<Card title=\"Team collaboration\">\nInvitations, mentions, comment notifications, and shared document alerts within your app.\n</Card>\n</CardGroup>\n\n## Best practices\n\n- **Verify your domain** for production use - emails from verified domains have better deliverability and avoid sandbox limits.\n- **Use environment variables** for API keys and never commit them to your codebase.\n- **Handle errors gracefully** - ask the agent to retry failed sends or log them for manual review.\n- **Personalize emails** - include the recipient's name and relevant context to improve engagement.\n- **Monitor bounce rates** - if Resend reports high bounces, check your recipient list quality and unsubscribe flow.\n\n<Warning>\nResend enforces rate limits based on your plan tier. If you're sending high volumes, coordinate with the agent to implement queueing or batch sending to stay within limits.\n</Warning>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| \"Invalid API key\" error | Double-check the `RESEND_API_KEY` variable value in your Emergent project. Regenerate the key in Resend if needed. |\n| Emails not arriving | Check your spam folder. Verify your sending domain in the Resend dashboard. Review Resend's **Logs** for delivery errors. |\n| Rate limit exceeded | Ask the agent to add retry logic with exponential backoff, or upgrade your Resend plan for higher limits. |\n| \"From\" address rejected | Ensure the sender address matches your verified domain. Sandbox emails must use `onboarding@resend.dev`. |","order":75,"parent_id":null,"icon":"mail","description":"Resend","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.875537+00:00","published_at":"2026-09-22T06:19:16.875537+00:00","published_content":"## Overview\n\nResend is a modern email API that makes it easy to send transactional and marketing emails from your Emergent app. With its developer-friendly interface and reliable delivery, Resend is ideal for password resets, welcome emails, notifications, and more.\n\nThis guide walks you through integrating Resend into your Emergent project so your AI agents can send emails on behalf of your application.\n\n## Using Resend with Emergent\n\nYou can use Resend in two ways:\n\n- **Automatically with Emergent's Universal LLM Key** - recommended.\n- **With your own Resend API key** - if you prefer to use your own Resend account and credentials.\n\n## Using Resend with Universal LLM Key\n\nThe preferred approach is to use Resend through **Emergent's Universal LLM Key**.\n\nDescribe the email functionality you want in your Emergent project, such as:\n\n> \"Send a confirmation email when a user submits the contact form.\"\n\nEmergent will configure Resend and handle the required credentials for your application.\n\nOnce connected, you can specify the email flows you want your application to support, such as password resets, welcome emails, or notifications.\n\n## Connecting Your Own Resend API Key\n\nIf you want to use your own Resend API key, you can provide your key when Emergent asks for your Resend credentials.\n\n<Steps>\n<Step title=\"Log in to Resend\">\nGo to [Resend](https://resend.com/) and log in or create an account.\n</Step>\n\n<Step title=\"Open API Keys\">\nGo directly to the [Resend API Keys page](https://resend.com/api-keys).\n\n**OR**\n\n- Open the Resend dashboard.\n- Go to **API Keys**.\n</Step>\n\n<Step title=\"Create the API Key\">\n- Click **Create API Key**.\n- Give the API key a name so you can identify which app it is for.\n  - Example: `Customer Feedback App`\n- Create the API key.\n</Step>\n\n<Step title=\"Copy the API Key\">\nCopy the complete secret API key immediately.\n\nIt will look like:\n\n`re_...`\n</Step>\n\n<Step title=\"Connect Resend to Emergent\">\n- When Emergent asks for your Resend credentials, provide the **API key**\n- Agent will securely configure the key and connect Resend to your application.\n</Step>\n\n<Step title=\"Verify Your Domain\">\n- For testing, you can start with your available verified sender setup.\n- To send emails to real customers, go to **Domains → Add Domain** in Resend.\n- Enter a domain that you own.\n- Add the DNS records provided by Resend to your domain provider.\n\nOnce connected, test your email flow to confirm that messages are being sent and delivered correctly.\n</Step>\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n<Card title=\"User onboarding\">\nWelcome emails, email verification links, and getting-started guides sent automatically when users sign up.\n</Card>\n\n<Card title=\"Transactional alerts\">\nOrder confirmations, shipping updates, payment receipts, and account security notifications.\n</Card>\n\n<Card title=\"Scheduled digests\">\nDaily or weekly summaries, activity reports, and content recommendations sent on a schedule.\n</Card>\n\n<Card title=\"Team collaboration\">\nInvitations, mentions, comment notifications, and shared document alerts within your app.\n</Card>\n</CardGroup>\n\n## Best practices\n\n- **Verify your domain** for production use - emails from verified domains have better deliverability and avoid sandbox limits.\n- **Use environment variables** for API keys and never commit them to your codebase.\n- **Handle errors gracefully** - ask the agent to retry failed sends or log them for manual review.\n- **Personalize emails** - include the recipient's name and relevant context to improve engagement.\n- **Monitor bounce rates** - if Resend reports high bounces, check your recipient list quality and unsubscribe flow.\n\n<Warning>\nResend enforces rate limits based on your plan tier. If you're sending high volumes, coordinate with the agent to implement queueing or batch sending to stay within limits.\n</Warning>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| \"Invalid API key\" error | Double-check the `RESEND_API_KEY` variable value in your Emergent project. Regenerate the key in Resend if needed. |\n| Emails not arriving | Check your spam folder. Verify your sending domain in the Resend dashboard. Review Resend's **Logs** for delivery errors. |\n| Rate limit exceeded | Ask the agent to add retry logic with exponential backoff, or upgrade your Resend plan for higher limits. |\n| \"From\" address rejected | Ensure the sender address matches your verified domain. Sandbox emails must use `onboarding@resend.dev`. |","published_title":"Resend","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"182b6cc1-ef61-4581-b56b-2430ef1921a6","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"SendGrid","slug":"sendgrid","content":"## Overview\n\nSendGrid is a cloud-based email delivery platform that enables your Emergent app to send transactional and marketing emails reliably. Common use cases include password resets, order confirmations, notifications, and automated email campaigns.\n\nThis guide shows you how to integrate SendGrid with your Emergent app using environment variables and the SendGrid API.\n\n<Note>\nSendGrid offers a free tier with 100 emails per day, which is sufficient for testing and small applications. Production apps typically require a paid plan.\n</Note>\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- A SendGrid account ([sign up](https://signup.sendgrid.com/))\n- An active Emergent project\n- Basic familiarity with environment variables\n\n## Setting up SendGrid\n\n<Steps>\n<Step title=\"Create a SendGrid API key\">\n1. Log in to your [SendGrid dashboard](https://app.sendgrid.com/)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Choose **Restricted Access** and enable **Mail Send** permissions (recommended for security)\n5. Name your key (e.g., `emergent-production`)\n6. Copy the generated API key immediately - it won't be shown again\n</Step>\n\n<Step title=\"Verify a sender identity\">\nSendGrid requires you to verify the email address or domain you'll send from:\n\n1. Go to **Settings** → **Sender Authentication**\n2. For testing: verify a **Single Sender** email address\n3. For production: set up **Domain Authentication** to improve deliverability\n\nCheck your inbox for the verification email and follow the link.\n</Step>\n\n<Step title=\"Add the API key to your Emergent app\">\nIn the Emergent chat, add your SendGrid API key as an environment variable:\n\n> Add environment variable `SENDGRID_API_KEY` with value `SG.xxxxx...`\n\nMark this variable as **secret** to prevent it from appearing in logs or client-side code.\n</Step>\n\n<Step title=\"Configure sender details\">\nStore your verified sender email as an environment variable for easy reuse:\n\n> Add environment variable `SENDGRID_FROM_EMAIL` with value `noreply@yourdomain.com`\n\nOptionally add `SENDGRID_FROM_NAME` for a friendly sender name.\n</Step>\n</Steps>\n\n## Sending emails from your app\n\nOnce configured, you can send emails using the SendGrid Node.js SDK or REST API. Here's how to implement common email scenarios:\n\n### Transactional emails\n\n*(The agent writes and wires up this code for you.)*\n\n*(The agent writes and wires up this code for you.)*\n\n### Using templates\n\nSendGrid's Dynamic Templates let you design emails visually and populate them with data:\n\n*(The agent writes and wires up this code for you.)*\n\n<Tip>\nCreate templates in the SendGrid dashboard under **Email API** → **Dynamic Templates**. Copy the template ID (starts with `d-`) and pass it in your code.\n</Tip>\n\n## Testing email delivery\n\n### Test mode\n\nDuring development, consider these strategies to avoid sending real emails:\n\n<Tabs>\n<Tab title=\"SendGrid sandbox\">\nSendGrid's sandbox mode validates requests without sending actual emails:\n\n*(The agent writes and wires up this code for you.)*\n</Tab>\n\n<Tab title=\"Test recipient\">\nSend all development emails to a test address:\n\n*(The agent writes and wires up this code for you.)*\n</Tab>\n</Tabs>\n\n### Monitoring delivery\n\nTrack email activity in the SendGrid dashboard:\n\n1. Go to **Activity** to see recent sends, bounces, and opens\n2. Check **Suppressions** for bounced or unsubscribed addresses\n3. Review **Statistics** for delivery rates and engagement metrics\n\n<Warning>\nHigh bounce rates can damage your sender reputation. Regularly clean your email list and honor unsubscribe requests.\n</Warning>\n\n## Common patterns in Emergent apps\n\n### Scheduled notifications\n\nUse SendGrid's `sendAt` parameter to schedule emails for a future time (up to 72 hours):\n\n*(The agent writes and wires up this code for you.)*\n\n### Batch sending\n\nSend the same email to multiple recipients efficiently:\n\n*(The agent writes and wires up this code for you.)*\n\n<Info>\nFor large batches (1000+ recipients), consider using SendGrid's batch ID feature to cancel or pause sends if needed.\n</Info>\n\n## Troubleshooting\n\n<AccordionGroup>\n<Accordion title=\"Emails not arriving\">\n- Verify your sender identity in the SendGrid dashboard\n- Check the **Activity** feed for delivery status and errors\n- Ensure `SENDGRID_API_KEY` is set correctly and has **Mail Send** permissions\n- Look for emails in spam/junk folders (improve this with domain authentication)\n</Accordion>\n\n<Accordion title=\"403 Forbidden error\">\nYour API key likely lacks the necessary permissions. Create a new key with **Mail Send** enabled under **Restricted Access**.\n</Accordion>\n\n<Accordion title=\"Rate limit errors\">\nFree accounts are limited to 100 emails per day. Upgrade your SendGrid plan or implement retry logic with exponential backoff for production apps.\n</Accordion>\n\n<Accordion title=\"Unsubscribe compliance\">\nInclude an unsubscribe link in marketing emails to comply with regulations:\n\n*(The agent writes and wires up this code for you.)*\n\nSendGrid automatically adds an unsubscribe footer when enabled.\n</Accordion>\n</AccordionGroup>\n\n## Best practices\n\n<CardGroup cols={2}>\n<Card title=\"Use templates\" icon=\"palette\">\nDesign emails visually in SendGrid and keep HTML out of your codebase. Templates are easier to update and A/B test.\n</Card>\n\n<Card title=\"Authenticate your domain\" icon=\"shield-check\">\nSet up SPF, DKIM, and DMARC records to improve deliverability and avoid the spam folder.\n</Card>\n\n<Card title=\"Handle errors gracefully\" icon=\"triangle-alert\">\nWrap `sgMail.send()` in try-catch blocks and log failures for investigation. Don't block user workflows on email delivery.\n</Card>\n\n<Card title=\"Monitor suppressions\" icon=\"ban\">\nRegularly check bounced and unsubscribed addresses. Remove them from your database to maintain a healthy sender reputation.\n</Card>\n</CardGroup>\n","order":76,"parent_id":null,"icon":"mail","description":"SendGrid","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.880989+00:00","published_at":"2026-09-22T06:19:16.880989+00:00","published_content":"## Overview\n\nSendGrid is a cloud-based email delivery platform that enables your Emergent app to send transactional and marketing emails reliably. Common use cases include password resets, order confirmations, notifications, and automated email campaigns.\n\nThis guide shows you how to integrate SendGrid with your Emergent app using environment variables and the SendGrid API.\n\n<Note>\nSendGrid offers a free tier with 100 emails per day, which is sufficient for testing and small applications. Production apps typically require a paid plan.\n</Note>\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- A SendGrid account ([sign up](https://signup.sendgrid.com/))\n- An active Emergent project\n- Basic familiarity with environment variables\n\n## Setting up SendGrid\n\n<Steps>\n<Step title=\"Create a SendGrid API key\">\n1. Log in to your [SendGrid dashboard](https://app.sendgrid.com/)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Choose **Restricted Access** and enable **Mail Send** permissions (recommended for security)\n5. Name your key (e.g., `emergent-production`)\n6. Copy the generated API key immediately - it won't be shown again\n</Step>\n\n<Step title=\"Verify a sender identity\">\nSendGrid requires you to verify the email address or domain you'll send from:\n\n1. Go to **Settings** → **Sender Authentication**\n2. For testing: verify a **Single Sender** email address\n3. For production: set up **Domain Authentication** to improve deliverability\n\nCheck your inbox for the verification email and follow the link.\n</Step>\n\n<Step title=\"Add the API key to your Emergent app\">\nIn the Emergent chat, add your SendGrid API key as an environment variable:\n\n> Add environment variable `SENDGRID_API_KEY` with value `SG.xxxxx...`\n\nMark this variable as **secret** to prevent it from appearing in logs or client-side code.\n</Step>\n\n<Step title=\"Configure sender details\">\nStore your verified sender email as an environment variable for easy reuse:\n\n> Add environment variable `SENDGRID_FROM_EMAIL` with value `noreply@yourdomain.com`\n\nOptionally add `SENDGRID_FROM_NAME` for a friendly sender name.\n</Step>\n</Steps>\n\n## Sending emails from your app\n\nOnce configured, you can send emails using the SendGrid Node.js SDK or REST API. Here's how to implement common email scenarios:\n\n### Transactional emails\n\n*(The agent writes and wires up this code for you.)*\n\n*(The agent writes and wires up this code for you.)*\n\n### Using templates\n\nSendGrid's Dynamic Templates let you design emails visually and populate them with data:\n\n*(The agent writes and wires up this code for you.)*\n\n<Tip>\nCreate templates in the SendGrid dashboard under **Email API** → **Dynamic Templates**. Copy the template ID (starts with `d-`) and pass it in your code.\n</Tip>\n\n## Testing email delivery\n\n### Test mode\n\nDuring development, consider these strategies to avoid sending real emails:\n\n<Tabs>\n<Tab title=\"SendGrid sandbox\">\nSendGrid's sandbox mode validates requests without sending actual emails:\n\n*(The agent writes and wires up this code for you.)*\n</Tab>\n\n<Tab title=\"Test recipient\">\nSend all development emails to a test address:\n\n*(The agent writes and wires up this code for you.)*\n</Tab>\n</Tabs>\n\n### Monitoring delivery\n\nTrack email activity in the SendGrid dashboard:\n\n1. Go to **Activity** to see recent sends, bounces, and opens\n2. Check **Suppressions** for bounced or unsubscribed addresses\n3. Review **Statistics** for delivery rates and engagement metrics\n\n<Warning>\nHigh bounce rates can damage your sender reputation. Regularly clean your email list and honor unsubscribe requests.\n</Warning>\n\n## Common patterns in Emergent apps\n\n### Scheduled notifications\n\nUse SendGrid's `sendAt` parameter to schedule emails for a future time (up to 72 hours):\n\n*(The agent writes and wires up this code for you.)*\n\n### Batch sending\n\nSend the same email to multiple recipients efficiently:\n\n*(The agent writes and wires up this code for you.)*\n\n<Info>\nFor large batches (1000+ recipients), consider using SendGrid's batch ID feature to cancel or pause sends if needed.\n</Info>\n\n## Troubleshooting\n\n<AccordionGroup>\n<Accordion title=\"Emails not arriving\">\n- Verify your sender identity in the SendGrid dashboard\n- Check the **Activity** feed for delivery status and errors\n- Ensure `SENDGRID_API_KEY` is set correctly and has **Mail Send** permissions\n- Look for emails in spam/junk folders (improve this with domain authentication)\n</Accordion>\n\n<Accordion title=\"403 Forbidden error\">\nYour API key likely lacks the necessary permissions. Create a new key with **Mail Send** enabled under **Restricted Access**.\n</Accordion>\n\n<Accordion title=\"Rate limit errors\">\nFree accounts are limited to 100 emails per day. Upgrade your SendGrid plan or implement retry logic with exponential backoff for production apps.\n</Accordion>\n\n<Accordion title=\"Unsubscribe compliance\">\nInclude an unsubscribe link in marketing emails to comply with regulations:\n\n*(The agent writes and wires up this code for you.)*\n\nSendGrid automatically adds an unsubscribe footer when enabled.\n</Accordion>\n</AccordionGroup>\n\n## Best practices\n\n<CardGroup cols={2}>\n<Card title=\"Use templates\" icon=\"palette\">\nDesign emails visually in SendGrid and keep HTML out of your codebase. Templates are easier to update and A/B test.\n</Card>\n\n<Card title=\"Authenticate your domain\" icon=\"shield-check\">\nSet up SPF, DKIM, and DMARC records to improve deliverability and avoid the spam folder.\n</Card>\n\n<Card title=\"Handle errors gracefully\" icon=\"triangle-alert\">\nWrap `sgMail.send()` in try-catch blocks and log failures for investigation. Don't block user workflows on email delivery.\n</Card>\n\n<Card title=\"Monitor suppressions\" icon=\"ban\">\nRegularly check bounced and unsubscribed addresses. Remove them from your database to maintain a healthy sender reputation.\n</Card>\n</CardGroup>\n","published_title":"SendGrid","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"dc79d4fe-da19-45cc-b1fd-7fe3e0f96e7f","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"ElevenLabs","slug":"elevenlabs","content":"## Overview\n\nElevenLabs provides AI-powered text-to-speech and voice synthesis services. Integrating ElevenLabs into your Emergent project lets you generate natural-sounding speech from text, create custom voices, and build voice-enabled experiences.\n\nThis guide walks you through setting up the ElevenLabs integration so your agents can call its API directly from your application.\n\n* * *\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- An active ElevenLabs account ([sign up here](https://elevenlabs.io))\n- An API key from your ElevenLabs dashboard\n- An Emergent project where you want to use voice synthesis\n\n<Note>\nElevenLabs offers a free tier with limited character quota. Check your plan limits in the ElevenLabs dashboard to ensure they meet your project's needs.\n</Note>\n\n* * *\n\n## Setup steps\n\n<Steps>\n\n<Step title=\"Describe your voice synthesis feature\">\n\nIn your Emergent workspace, open the **chat** and describe what you want to build using ElevenLabs. For example:\n\n> Add a \"Speak\" button next to each article. When clicked, use ElevenLabs to convert the article text to speech and play it.\n\n> Create a voice settings page where users can choose from available ElevenLabs voices. Store their preference and use that voice for all text-to-speech playback.\n\n> When a user submits a story, generate an audio narration using ElevenLabs and display an audio player on the story detail page.\n\nThe agents will identify the ElevenLabs integration requirement and prompt you for the API key if it is needed.\n\n</Step>\n\n<Step title=\"Obtain your ElevenLabs API key\">\n\n1. Log in to your [ElevenLabs account](https://elevenlabs.io/)\n2. Navigate to your **Profile Settings** (click your avatar in the top-right corner)\n3. Select the **API Keys** tab\n4. Click **Create API Key** or copy an existing key\n5. Store the key securely\n\n<Warning>\nTreat your API key like a password. Do not commit it to version control or share it publicly.\n</Warning>\n\n</Step>\n\n<Step title=\"Add the API key to your Emergent project\">\n\nWhen Emergent asks for the ElevenLabs API key:\n\n1. Provide the API key.\n2. Agent will securely configure and wire the key into the project.\n\nThe agent will handle the required secret configuration and use the key to set up the integration.\n\n</Step>\n\n<Step title=\"Implement and test the integration\">\n\nThe agents will:\n\n- Install the ElevenLabs SDK (if needed)\n- Implement API calls using your stored key\n- Build the UI components for playback or voice selection\n- Handle error states (quota exceeded, network issues)\n\nOnce the agents publish your feature:\n\n1. Navigate to the part of your app that uses ElevenLabs\n2. Trigger the text-to-speech action\n3. Verify that audio is generated and plays correctly\n4. Check your ElevenLabs dashboard to confirm API usage is being tracked\n\n<Tip>\nStart with short text samples during testing to conserve your character quota.\n</Tip>\n\nIf you encounter errors, describe the issue in chat:\n\n> The ElevenLabs audio isn't playing. I see an error: [paste error message].\n\nThe agents will debug and fix the integration.\n\n</Step>\n\n</Steps>\n\n* * *\n\n## Common use cases\n\n<CardGroup cols={2}>\n\n<Card title=\"Article narration\">\nGenerate audio versions of blog posts or articles for accessibility and multi-modal consumption.\n</Card>\n\n<Card title=\"Voice assistants\">\nBuild conversational interfaces that respond with natural-sounding speech.\n</Card>\n\n<Card title=\"Audiobook generation\">\nConvert written content into audiobook-style narration with custom voices.\n</Card>\n\n<Card title=\"Notification voiceovers\">\nAdd spoken alerts or announcements to your app for visually impaired users.\n</Card>\n\n</CardGroup>\n\n* * *\n\n## Configuration options\n\nYou can customize how ElevenLabs is used in your project by describing preferences to the agents:\n\n| Option | Description | Example instruction |\n| --- | --- | --- |\n| **Voice selection** | Choose from ElevenLabs' library of pre-made voices | \"Use the 'Rachel' voice for all narration\" |\n| **Voice settings** | Adjust stability, clarity, and style parameters | \"Set voice stability to 0.75 and clarity to 0.8\" |\n| **Model selection** | Pick a specific ElevenLabs model (multilingual, turbo, etc.) | \"Use the multilingual v2 model for better accent handling\" |\n| **Streaming** | Enable real-time audio streaming for low-latency playback | \"Stream audio as it's generated instead of waiting for the full file\" |\n| **Caching** | Store generated audio to reduce API calls | \"Cache generated speech for 24 hours per unique text input\" |\n\n<Note>\nThe agents will suggest sensible defaults based on your use case. You can always refine settings by describing adjustments in chat.\n</Note>\n\n* * *\n\n## Monitoring usage\n\nElevenLabs tracks character usage against your plan quota. To monitor:\n\n1. Visit your [ElevenLabs dashboard](https://elevenlabs.io/app/usage)\n2. Review **Character Usage** for the current billing period\n3. Set up usage alerts if your plan supports them\n\n<Warning>\nIf you exceed your quota, API requests will fail until you upgrade your plan or your quota resets. Build error handling into your app to gracefully inform users when synthesis is unavailable.\n</Warning>\n\nYou can instruct the agents to implement quota-aware features:\n\n> Show a warning in the admin panel when ElevenLabs usage reaches 80% of the monthly quota.\n\n* * *\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| **Audio doesn't play after generation** | **Possible causes:** The audio file URL is expired or inaccessible; Browser autoplay policies are blocking playback; CORS issues if hosting audio on a different domain. **Solutions:** Describe the issue in chat: \"Audio generated by ElevenLabs won't play in the browser\"; Agents will add user-initiated playback controls or adjust CORS headers; For mobile apps, ensure audio permissions are requested |\n| **API key authentication fails** | **Check:** The environment variable name is exactly `ELEVENLABS_API_KEY`; The key was copied correctly (no extra spaces); Your ElevenLabs account is active and the key hasn't been revoked. **Fix:** Re-add the key by telling the agents: \"Update the ElevenLabs API key to [paste new key]\" |\n| **Quota exceeded errors** | **Error message:** `\"quota_exceeded\"` or similar in API responses. **Immediate fix:** Upgrade your ElevenLabs plan, or wait for your quota to reset (check your billing cycle in the ElevenLabs dashboard). **Long-term solution:** Ask the agents to implement caching: \"Cache ElevenLabs audio for identical text inputs to reduce API calls.\" |\n| **Generated voice sounds unnatural** | **Tuning options:** Try a different voice from the ElevenLabs library; Adjust stability and clarity settings (lower stability = more expressive, higher = more consistent); Use the higher-quality model if your plan supports it. **Instruction example:** \"Switch to the 'Josh' voice and increase stability to 0.9 for clearer speech.\" |\n\n* * *\n\n## Best practices\n\n<Tip>\n**Cache aggressively:** Store generated audio for repeated text to avoid redundant API calls. **Truncate long inputs:** ElevenLabs charges per character; summarize or chunk very long documents. **Use streaming:** For real-time applications, stream audio as it's generated to reduce perceived latency.\n</Tip>\n\n<Note>\nElevenLabs integrations are powerful for making content accessible to visually impaired users and those who prefer audio. Combine with transcripts or captions for full accessibility coverage.\n</Note>\n\n<Note>\nIf you're building a public-facing app, implement rate limiting or user quotas to prevent abuse and unexpected billing spikes.\n</Note>","order":78,"parent_id":null,"icon":"image","description":"Setting up ElevenLabs.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.877440+00:00","published_at":"2026-09-22T06:19:16.877440+00:00","published_content":"## Overview\n\nElevenLabs provides AI-powered text-to-speech and voice synthesis services. Integrating ElevenLabs into your Emergent project lets you generate natural-sounding speech from text, create custom voices, and build voice-enabled experiences.\n\nThis guide walks you through setting up the ElevenLabs integration so your agents can call its API directly from your application.\n\n* * *\n\n## Prerequisites\n\nBefore you begin, you'll need:\n\n- An active ElevenLabs account ([sign up here](https://elevenlabs.io))\n- An API key from your ElevenLabs dashboard\n- An Emergent project where you want to use voice synthesis\n\n<Note>\nElevenLabs offers a free tier with limited character quota. Check your plan limits in the ElevenLabs dashboard to ensure they meet your project's needs.\n</Note>\n\n* * *\n\n## Setup steps\n\n<Steps>\n\n<Step title=\"Describe your voice synthesis feature\">\n\nIn your Emergent workspace, open the **chat** and describe what you want to build using ElevenLabs. For example:\n\n> Add a \"Speak\" button next to each article. When clicked, use ElevenLabs to convert the article text to speech and play it.\n\n> Create a voice settings page where users can choose from available ElevenLabs voices. Store their preference and use that voice for all text-to-speech playback.\n\n> When a user submits a story, generate an audio narration using ElevenLabs and display an audio player on the story detail page.\n\nThe agents will identify the ElevenLabs integration requirement and prompt you for the API key if it is needed.\n\n</Step>\n\n<Step title=\"Obtain your ElevenLabs API key\">\n\n1. Log in to your [ElevenLabs account](https://elevenlabs.io/)\n2. Navigate to your **Profile Settings** (click your avatar in the top-right corner)\n3. Select the **API Keys** tab\n4. Click **Create API Key** or copy an existing key\n5. Store the key securely\n\n<Warning>\nTreat your API key like a password. Do not commit it to version control or share it publicly.\n</Warning>\n\n</Step>\n\n<Step title=\"Add the API key to your Emergent project\">\n\nWhen Emergent asks for the ElevenLabs API key:\n\n1. Provide the API key.\n2. Agent will securely configure and wire the key into the project.\n\nThe agent will handle the required secret configuration and use the key to set up the integration.\n\n</Step>\n\n<Step title=\"Implement and test the integration\">\n\nThe agents will:\n\n- Install the ElevenLabs SDK (if needed)\n- Implement API calls using your stored key\n- Build the UI components for playback or voice selection\n- Handle error states (quota exceeded, network issues)\n\nOnce the agents publish your feature:\n\n1. Navigate to the part of your app that uses ElevenLabs\n2. Trigger the text-to-speech action\n3. Verify that audio is generated and plays correctly\n4. Check your ElevenLabs dashboard to confirm API usage is being tracked\n\n<Tip>\nStart with short text samples during testing to conserve your character quota.\n</Tip>\n\nIf you encounter errors, describe the issue in chat:\n\n> The ElevenLabs audio isn't playing. I see an error: [paste error message].\n\nThe agents will debug and fix the integration.\n\n</Step>\n\n</Steps>\n\n* * *\n\n## Common use cases\n\n<CardGroup cols={2}>\n\n<Card title=\"Article narration\">\nGenerate audio versions of blog posts or articles for accessibility and multi-modal consumption.\n</Card>\n\n<Card title=\"Voice assistants\">\nBuild conversational interfaces that respond with natural-sounding speech.\n</Card>\n\n<Card title=\"Audiobook generation\">\nConvert written content into audiobook-style narration with custom voices.\n</Card>\n\n<Card title=\"Notification voiceovers\">\nAdd spoken alerts or announcements to your app for visually impaired users.\n</Card>\n\n</CardGroup>\n\n* * *\n\n## Configuration options\n\nYou can customize how ElevenLabs is used in your project by describing preferences to the agents:\n\n| Option | Description | Example instruction |\n| --- | --- | --- |\n| **Voice selection** | Choose from ElevenLabs' library of pre-made voices | \"Use the 'Rachel' voice for all narration\" |\n| **Voice settings** | Adjust stability, clarity, and style parameters | \"Set voice stability to 0.75 and clarity to 0.8\" |\n| **Model selection** | Pick a specific ElevenLabs model (multilingual, turbo, etc.) | \"Use the multilingual v2 model for better accent handling\" |\n| **Streaming** | Enable real-time audio streaming for low-latency playback | \"Stream audio as it's generated instead of waiting for the full file\" |\n| **Caching** | Store generated audio to reduce API calls | \"Cache generated speech for 24 hours per unique text input\" |\n\n<Note>\nThe agents will suggest sensible defaults based on your use case. You can always refine settings by describing adjustments in chat.\n</Note>\n\n* * *\n\n## Monitoring usage\n\nElevenLabs tracks character usage against your plan quota. To monitor:\n\n1. Visit your [ElevenLabs dashboard](https://elevenlabs.io/app/usage)\n2. Review **Character Usage** for the current billing period\n3. Set up usage alerts if your plan supports them\n\n<Warning>\nIf you exceed your quota, API requests will fail until you upgrade your plan or your quota resets. Build error handling into your app to gracefully inform users when synthesis is unavailable.\n</Warning>\n\nYou can instruct the agents to implement quota-aware features:\n\n> Show a warning in the admin panel when ElevenLabs usage reaches 80% of the monthly quota.\n\n* * *\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| **Audio doesn't play after generation** | **Possible causes:** The audio file URL is expired or inaccessible; Browser autoplay policies are blocking playback; CORS issues if hosting audio on a different domain. **Solutions:** Describe the issue in chat: \"Audio generated by ElevenLabs won't play in the browser\"; Agents will add user-initiated playback controls or adjust CORS headers; For mobile apps, ensure audio permissions are requested |\n| **API key authentication fails** | **Check:** The environment variable name is exactly `ELEVENLABS_API_KEY`; The key was copied correctly (no extra spaces); Your ElevenLabs account is active and the key hasn't been revoked. **Fix:** Re-add the key by telling the agents: \"Update the ElevenLabs API key to [paste new key]\" |\n| **Quota exceeded errors** | **Error message:** `\"quota_exceeded\"` or similar in API responses. **Immediate fix:** Upgrade your ElevenLabs plan, or wait for your quota to reset (check your billing cycle in the ElevenLabs dashboard). **Long-term solution:** Ask the agents to implement caching: \"Cache ElevenLabs audio for identical text inputs to reduce API calls.\" |\n| **Generated voice sounds unnatural** | **Tuning options:** Try a different voice from the ElevenLabs library; Adjust stability and clarity settings (lower stability = more expressive, higher = more consistent); Use the higher-quality model if your plan supports it. **Instruction example:** \"Switch to the 'Josh' voice and increase stability to 0.9 for clearer speech.\" |\n\n* * *\n\n## Best practices\n\n<Tip>\n**Cache aggressively:** Store generated audio for repeated text to avoid redundant API calls. **Truncate long inputs:** ElevenLabs charges per character; summarize or chunk very long documents. **Use streaming:** For real-time applications, stream audio as it's generated to reduce perceived latency.\n</Tip>\n\n<Note>\nElevenLabs integrations are powerful for making content accessible to visually impaired users and those who prefer audio. Combine with transcripts or captions for full accessibility coverage.\n</Note>\n\n<Note>\nIf you're building a public-facing app, implement rate limiting or user quotas to prevent abuse and unexpected billing spikes.\n</Note>","published_title":"ElevenLabs","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"d759e7ba-6ca4-4b9f-b0c9-97f762342b3a","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"AI media generation (image/video/audio)","slug":"ai-media-generation-image-video-audio","content":"## Overview\n\nEmergent lets you generate images, video and audio directly from your workspace using state-of-the-art AI models. Each media type consumes credits at different rates depending on model size, quality settings and output duration.\n\nIn-app media generation is also available through Emergent-managed connectors: add the **Image Generation**, **Speech-to-Text**, or **Text-to-Speech** tile from Manage → Integrations (no API key needed). \n\n---\n\n## Supported models and credit multipliers\n\nThe table below shows the available models and their credit cost per generation. Credit multipliers are applied **in addition to** the base credit cost for each API call.\n\n| Model | Provider | Output type | Credit multiplier | Typical use |\n|-------|----------|-------------|-------------------|-------------|\n| **Imagen 4** | Google | Image | 5× | High-quality, photorealistic images with accurate text rendering |\n| **GPT Image 1** | OpenAI | Image | standard rate | General-purpose image generation, illustrations and concept art |\n| **Sora 2** | OpenAI | Video | 10× | Text-to-video and image-to-video, cinematic quality (4/8/12 seconds, default 4) |\n| **Veo-3** | Google | Video | 8× | High-fidelity video from text prompts, natural motion and lighting |\n| **ElevenLabs** | ElevenLabs | Audio (voice) | 3× | Natural voice synthesis, multilingual support and voice cloning |\n| **Suno** | Suno | Audio (music) | 4× | Music generation from text descriptions, multiple styles and genres |\n\n<Note title=\"Free tier restrictions\">\nFree tier accounts cannot use compute-intensive media models such as Veo-3 and Sora 2.\n</Note>\n\n<Note title=\"Credit balance\">\nCheck your current credit balance and recharge options on the [Managing credit usage](/managing-credit-usage) page.\n</Note>\n\n---\n\n## How to generate media\n\n<Steps>\n\n<Step title=\"Describe your intent in chat\">\nAsk the AI agent to generate an image, video or audio clip. Be specific about style, mood, duration and any other constraints.\n\nExample prompts:\n- \"Generate a hero image for the landing page showing a futuristic cityscape at sunset\"\n- \"Create a video intro with our logo animating in\"\n- \"Generate a calm voiceover for the tutorial narration in a British accent\"\n</Step>\n\n<Step title=\"Agent selects the model\">\nThe agent automatically picks the most suitable model based on your request. If you want a specific provider, mention it explicitly (e.g. \"use Imagen for this\" or \"generate with Sora\").\n</Step>\n\n<Step title=\"Media is generated and inserted\">\nThe agent generates the asset, uploads it to your workspace storage and inserts a reference in your codebase or [database](/database-mongodb). You'll see a preview in the chat and a credit deduction in your usage log.\n</Step>\n\n</Steps>\n\n<Tip>\nFor long or high-quality video, generation can take several minutes. The agent will keep you updated on progress.\n</Tip>\n\n---\n\n## Image generation\n\n### Imagen 4 vs GPT Image 1\n\n- **Imagen 4** excels at photorealism, accurate text rendering in images and complex scenes with multiple objects.\n- **GPT Image 1** is more cost-effective for illustrations, concept art and stylized visuals.\n\nBoth models support aspect ratio control and style prompts. The agent infers the best choice unless you specify a preference.\n\n### Common workflows\n\n<CardGroup cols={2}>\n <Card title=\"Hero images\" icon=\"image\">\n Generate large, high-resolution visuals for landing pages and marketing materials.\n </Card>\n <Card title=\"UI placeholders\" icon=\"palette\">\n Create consistent placeholder graphics for design mockups and prototypes.\n </Card>\n <Card title=\"Product renders\" icon=\"cube\">\n Produce photorealistic product shots from text descriptions.\n </Card>\n <Card title=\"Icon sets\" icon=\"shapes\">\n Generate cohesive icon families in a specific style.\n </Card>\n</CardGroup>\n\n---\n\n## Video generation\n\n### Sora 2 vs Veo-3\n\n- **Sora 2** (OpenAI) produces cinematic, story-driven sequences with strong character consistency and smooth motion. It supports both text-to-video and image-to-video workflows. Clips are available in 4, 8 or 12 seconds (default 4 seconds).\n- **Veo-3** (Google) offers high-fidelity output with realistic lighting and natural camera movement. It's particularly strong for product demos and architectural walkthroughs.\n\nFor longer sequences, the agent stitches multiple clips or edits them programmatically.\n\n<Warning title=\"Video generation is credit-intensive\">\nVideo generation is highly credit-intensive. Review the cost estimate before confirming generation.\n</Warning>\n\n### Supported input formats\n\n- **Text prompt** - describe the scene, action and style.\n- **Starting image** - provide a still frame and describe the motion.\n- **Style reference** - link to an existing video or describe a visual style (e.g. \"documentary feel\" or \"anime aesthetic\").\n\n---\n\n## Audio generation\n\n### ElevenLabs (voice synthesis)\n\nElevenLabs converts text to natural-sounding speech in dozens of languages. You can choose from a library of pre-built voices or clone a custom voice by uploading sample audio.\n\n**Use cases:**\n- Tutorial narration and onboarding flows.\n- Dynamic in-app announcements or alerts.\n- Voiceovers for video content.\n\nFor detailed configuration (voice selection, pitch, speed), see the [ElevenLabs](/elevenlabs) integration page.\n\n### Suno (music generation)\n\nSuno generates original music from text descriptions. Specify genre, mood, instrumentation and duration (up to 4 minutes per clip).\n\n**Use cases:**\n- Background music for video content.\n- Custom app soundtracks and loading screens.\n- Placeholder audio for prototypes.\n\n<Info>\nGenerated music is royalty-free for use within your Emergent projects. For commercial redistribution outside the platform, review Suno's licensing terms.\n</Info>\n\n---\n\n## Best practices\n\n<AccordionGroup>\n\n<Accordion title=\"Write detailed prompts\">\nThe more specific your description, the better the output. Include style, lighting, camera angle, mood and any objects or text that must appear. For video, describe the start and end states explicitly.\n</Accordion>\n\n<Accordion title=\"Iterate in chat\">\nIf the first result isn't quite right, ask the agent to refine it (\"make the lighting warmer,\" \"add a logo in the top-right corner\"). Each refinement is a new generation and consumes additional credits.\n</Accordion>\n\n<Accordion title=\"Reuse assets across pages\">\nOnce generated, media files are stored in your workspace. Reference them in multiple places (pages, emails, database records) without regenerating.\n</Accordion>\n\n<Accordion title=\"Monitor credit usage\">\nCheck the credit log regularly if you're generating large volumes of media. Video and music generation can consume credits quickly, especially at high quality settings.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Integration with the workspace\n\nAll generated media is automatically:\n- Uploaded to your workspace storage.\n- Optimized for web delivery (images are converted to WebP, videos to H.264/VP9).\n- Accessible via a permanent URL that works in both development and production.\n\nIf you publish to a [custom domain](/custom-domain), media URLs are rewritten to serve from your domain's asset CDN.\n\nFor programmatic access (e.g. storing media URLs in your [MongoDB database](/database-mongodb)), the agent provides the public URL after generation.\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n <Card title=\"The Universal LLM Key\" icon=\"key\" href=\"/the-universal-llm-key\">\n How Emergent routes API calls and tracks usage\n </Card>\n <Card title=\"Managing credit usage\" icon=\"coins\" href=\"/managing-credit-usage\">\n Manage your credit balance and auto-recharge settings\n </Card>\n <Card title=\"ElevenLabs integration\" icon=\"microphone\" href=\"/elevenlabs\">\n Deep-dive on voice synthesis and cloning\n </Card>\n <Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\n Definitions of workspace, agent, credit and other key terms\n </Card>\n</CardGroup>","order":82,"parent_id":null,"icon":"sparkles","description":"AI image/video/audio generation models with credit multipliers (Imagen 4, GPT Image 1, Sora 2, Veo-3, ElevenLabs, Suno).","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.883913+00:00","published_at":"2026-09-22T06:19:16.883913+00:00","published_content":"## Overview\n\nEmergent lets you generate images, video and audio directly from your workspace using state-of-the-art AI models. Each media type consumes credits at different rates depending on model size, quality settings and output duration.\n\nIn-app media generation is also available through Emergent-managed connectors: add the **Image Generation**, **Speech-to-Text**, or **Text-to-Speech** tile from Manage → Integrations (no API key needed). \n\n---\n\n## Supported models and credit multipliers\n\nThe table below shows the available models and their credit cost per generation. Credit multipliers are applied **in addition to** the base credit cost for each API call.\n\n| Model | Provider | Output type | Credit multiplier | Typical use |\n|-------|----------|-------------|-------------------|-------------|\n| **Imagen 4** | Google | Image | 5× | High-quality, photorealistic images with accurate text rendering |\n| **GPT Image 1** | OpenAI | Image | standard rate | General-purpose image generation, illustrations and concept art |\n| **Sora 2** | OpenAI | Video | 10× | Text-to-video and image-to-video, cinematic quality (4/8/12 seconds, default 4) |\n| **Veo-3** | Google | Video | 8× | High-fidelity video from text prompts, natural motion and lighting |\n| **ElevenLabs** | ElevenLabs | Audio (voice) | 3× | Natural voice synthesis, multilingual support and voice cloning |\n| **Suno** | Suno | Audio (music) | 4× | Music generation from text descriptions, multiple styles and genres |\n\n<Note title=\"Free tier restrictions\">\nFree tier accounts cannot use compute-intensive media models such as Veo-3 and Sora 2.\n</Note>\n\n<Note title=\"Credit balance\">\nCheck your current credit balance and recharge options on the [Managing credit usage](/managing-credit-usage) page.\n</Note>\n\n---\n\n## How to generate media\n\n<Steps>\n\n<Step title=\"Describe your intent in chat\">\nAsk the AI agent to generate an image, video or audio clip. Be specific about style, mood, duration and any other constraints.\n\nExample prompts:\n- \"Generate a hero image for the landing page showing a futuristic cityscape at sunset\"\n- \"Create a video intro with our logo animating in\"\n- \"Generate a calm voiceover for the tutorial narration in a British accent\"\n</Step>\n\n<Step title=\"Agent selects the model\">\nThe agent automatically picks the most suitable model based on your request. If you want a specific provider, mention it explicitly (e.g. \"use Imagen for this\" or \"generate with Sora\").\n</Step>\n\n<Step title=\"Media is generated and inserted\">\nThe agent generates the asset, uploads it to your workspace storage and inserts a reference in your codebase or [database](/database-mongodb). You'll see a preview in the chat and a credit deduction in your usage log.\n</Step>\n\n</Steps>\n\n<Tip>\nFor long or high-quality video, generation can take several minutes. The agent will keep you updated on progress.\n</Tip>\n\n---\n\n## Image generation\n\n### Imagen 4 vs GPT Image 1\n\n- **Imagen 4** excels at photorealism, accurate text rendering in images and complex scenes with multiple objects.\n- **GPT Image 1** is more cost-effective for illustrations, concept art and stylized visuals.\n\nBoth models support aspect ratio control and style prompts. The agent infers the best choice unless you specify a preference.\n\n### Common workflows\n\n<CardGroup cols={2}>\n <Card title=\"Hero images\" icon=\"image\">\n Generate large, high-resolution visuals for landing pages and marketing materials.\n </Card>\n <Card title=\"UI placeholders\" icon=\"palette\">\n Create consistent placeholder graphics for design mockups and prototypes.\n </Card>\n <Card title=\"Product renders\" icon=\"cube\">\n Produce photorealistic product shots from text descriptions.\n </Card>\n <Card title=\"Icon sets\" icon=\"shapes\">\n Generate cohesive icon families in a specific style.\n </Card>\n</CardGroup>\n\n---\n\n## Video generation\n\n### Sora 2 vs Veo-3\n\n- **Sora 2** (OpenAI) produces cinematic, story-driven sequences with strong character consistency and smooth motion. It supports both text-to-video and image-to-video workflows. Clips are available in 4, 8 or 12 seconds (default 4 seconds).\n- **Veo-3** (Google) offers high-fidelity output with realistic lighting and natural camera movement. It's particularly strong for product demos and architectural walkthroughs.\n\nFor longer sequences, the agent stitches multiple clips or edits them programmatically.\n\n<Warning title=\"Video generation is credit-intensive\">\nVideo generation is highly credit-intensive. Review the cost estimate before confirming generation.\n</Warning>\n\n### Supported input formats\n\n- **Text prompt** - describe the scene, action and style.\n- **Starting image** - provide a still frame and describe the motion.\n- **Style reference** - link to an existing video or describe a visual style (e.g. \"documentary feel\" or \"anime aesthetic\").\n\n---\n\n## Audio generation\n\n### ElevenLabs (voice synthesis)\n\nElevenLabs converts text to natural-sounding speech in dozens of languages. You can choose from a library of pre-built voices or clone a custom voice by uploading sample audio.\n\n**Use cases:**\n- Tutorial narration and onboarding flows.\n- Dynamic in-app announcements or alerts.\n- Voiceovers for video content.\n\nFor detailed configuration (voice selection, pitch, speed), see the [ElevenLabs](/elevenlabs) integration page.\n\n### Suno (music generation)\n\nSuno generates original music from text descriptions. Specify genre, mood, instrumentation and duration (up to 4 minutes per clip).\n\n**Use cases:**\n- Background music for video content.\n- Custom app soundtracks and loading screens.\n- Placeholder audio for prototypes.\n\n<Info>\nGenerated music is royalty-free for use within your Emergent projects. For commercial redistribution outside the platform, review Suno's licensing terms.\n</Info>\n\n---\n\n## Best practices\n\n<AccordionGroup>\n\n<Accordion title=\"Write detailed prompts\">\nThe more specific your description, the better the output. Include style, lighting, camera angle, mood and any objects or text that must appear. For video, describe the start and end states explicitly.\n</Accordion>\n\n<Accordion title=\"Iterate in chat\">\nIf the first result isn't quite right, ask the agent to refine it (\"make the lighting warmer,\" \"add a logo in the top-right corner\"). Each refinement is a new generation and consumes additional credits.\n</Accordion>\n\n<Accordion title=\"Reuse assets across pages\">\nOnce generated, media files are stored in your workspace. Reference them in multiple places (pages, emails, database records) without regenerating.\n</Accordion>\n\n<Accordion title=\"Monitor credit usage\">\nCheck the credit log regularly if you're generating large volumes of media. Video and music generation can consume credits quickly, especially at high quality settings.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Integration with the workspace\n\nAll generated media is automatically:\n- Uploaded to your workspace storage.\n- Optimized for web delivery (images are converted to WebP, videos to H.264/VP9).\n- Accessible via a permanent URL that works in both development and production.\n\nIf you publish to a [custom domain](/custom-domain), media URLs are rewritten to serve from your domain's asset CDN.\n\nFor programmatic access (e.g. storing media URLs in your [MongoDB database](/database-mongodb)), the agent provides the public URL after generation.\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n <Card title=\"The Universal LLM Key\" icon=\"key\" href=\"/the-universal-llm-key\">\n How Emergent routes API calls and tracks usage\n </Card>\n <Card title=\"Managing credit usage\" icon=\"coins\" href=\"/managing-credit-usage\">\n Manage your credit balance and auto-recharge settings\n </Card>\n <Card title=\"ElevenLabs integration\" icon=\"microphone\" href=\"/elevenlabs\">\n Deep-dive on voice synthesis and cloning\n </Card>\n <Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\n Definitions of workspace, agent, credit and other key terms\n </Card>\n</CardGroup>","published_title":"AI media generation (image/video/audio)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"b6751958-c38a-48d5-beb2-68c5bf580185","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Shopify","slug":"shopify","content":"## Overview\n\nEmergent's Shopify integration lets your app connect to Shopify stores, retrieve product catalogs, manage orders, and synchronize inventory - all through a simple API connection. This guide walks you through setting up the integration so your app can interact with Shopify data.\n\n<Note>\nBefore you begin, you'll need a Shopify store (or Partner account with a development store) and admin access to install apps and generate API credentials.\n</Note>\n\n## Prerequisites\n\n- A Shopify store or development store\n- Admin permissions to install apps and manage API credentials\n- An active Emergent project where you want to add Shopify functionality\n\n## Setup process\n\n<Steps>\n\n<Step title=\"Log in to Shopify\">\n\nGo to [**https://dev.shopify.com**](https://dev.shopify.com) (or [partners.shopify.com](http://partners.shopify.com)) and sign in to your account/organization.\n\n</Step>\n\n<Step title=\"Create a Shopify app\">\n\n1. In the left sidebar, click **Apps** → **Create app** → **Build from scratch**\n2. Enter an app name (e.g., \"Catalog Manager\")\n3. Click **Create**\n\n</Step>\n\n<Step title=\"Configure Admin API scopes\">\n\nIn your app:\n\n1. Open **Configuration** (or **API access**)\n2. Under **Admin API access scopes**, enable the scopes your integration requires (for example, `write_products`, `read_products`, `read_orders`, `write_orders`, `read_inventory`, `write_inventory`)\n3. Click **Save**\n4. **Release the app version**\n\n</Step>\n\n<Step title=\"Install the app on a store\">\n\n1. Open your app and find **Install** (or the **Installs** section)\n2. Click **Select store to install**\n3. Choose your development store and click **Install**\n4. Confirm that the app has been installed successfully\n\n</Step>\n\n<Step title=\"Retrieve your Client ID and Secret\">\n\nAfter installing the app:\n\n1. Go to your app's **Settings** → **API credentials** (or **Client credentials**)\n2. Copy the **Client ID**\n3. Copy the **Client Secret**\n\n</Step>\n\n<Step title=\"Get the store domain\">\n\n1. Go to Shopify Admin and open your store\n2. Look at the browser URL: `admin.shopify.com/store/HANDLE`\n3. Your Shopify store domain is `HANDLE.myshopify.com`\n\nYou will need the **Client ID, Client Secret, and store domain** for the integration.\n\n</Step>\n\n<Step title=\"Test the connection\">\n\nVerify the integration by describing a simple query to Emergent:\n\n> \"Fetch the first 10 products from my Shopify store and display their titles and prices.\"\n\nEmergent will generate code that uses the Shopify API to retrieve products. If the connection is successful, you'll see product data in your app.\n\n</Step>\n\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n\n<Card title=\"Product catalog sync\" icon=\"box\">\nDisplay your Shopify inventory in a custom storefront or mobile app\n</Card>\n\n<Card title=\"Order management\" icon=\"receipt\">\nCreate, update, and track orders programmatically\n</Card>\n\n<Card title=\"Inventory monitoring\" icon=\"warehouse\">\nReal-time stock level checks and low-inventory alerts\n</Card>\n\n<Card title=\"Customer data\" icon=\"users\">\nRetrieve customer profiles, order histories, and preferences\n</Card>\n\n</CardGroup>\n\n## API rate limits\n\nShopify enforces rate limits on API calls to protect store performance. The standard REST Admin API allows:\n\n- **2 requests per second** for most endpoints\n- **4 requests per second** for GraphQL (with cost-based throttling)\n\n<Warning>\nIf your app exceeds rate limits, Shopify will return `429 Too Many Requests` errors. Build in exponential backoff and respect the `Retry-After` header in responses.\n</Warning>\n\n<Note>\nEach Shopify playbook run costs approximately ~1.5 credits.\n</Note>\n\n## Webhooks for real-time updates (Optional)\n\nInstead of polling Shopify for changes, register webhooks to receive instant notifications when products, orders, or inventory change:\n\n1. In your Shopify app settings, go to **Webhooks**\n2. Click **Create webhook**\n3. Select the event (e.g., `products/update`, `orders/create`)\n4. Enter your Emergent app's webhook endpoint URL\n5. Click **Save**\n\nEmergent can generate webhook handlers that parse and store incoming Shopify events.\n\n<Tip>\nDescribe your webhook requirements in chat - Emergent will set up the endpoint, parse the payload, and help you store or act on the data.\n</Tip>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| API credentials not working | Verify the Client ID and Client Secret were copied correctly (no extra spaces) - Confirm the app is installed on the correct store - Check that required API scopes are enabled in the app configuration - Regenerate credentials if you suspect they were compromised |\n| Missing product data | Ensure `read_products` scope is granted - Verify products are published to the sales channel your app is accessing - Check that you're querying the correct store (if you have multiple) |\n| Orders not appearing | Ensure the `read_all_orders` scope is granted in your custom app configuration |\n| Rate limit errors | Implement exponential backoff in your request logic - Cache frequently accessed data to reduce API calls - Consider switching to GraphQL for more efficient bulk queries |\n\n## Additional resources\n\n- [Shopify Admin API documentation](https://shopify.dev/docs/api/admin)\n- [Shopify GraphQL reference](https://shopify.dev/docs/api/admin-graphql)\n- [Webhook event reference](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook)\n\n<Tip>\nOnce your Shopify integration is live, you can expand it by asking Emergent to \"add a product search feature\" or \"create a dashboard showing today's orders\" - the AI will build on your existing Shopify connection.\n</Tip>","order":85,"parent_id":null,"icon":"layout-grid","description":"Setting up Shopify integration.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:16.868547+00:00","published_at":"2026-09-22T06:19:16.868547+00:00","published_content":"## Overview\n\nEmergent's Shopify integration lets your app connect to Shopify stores, retrieve product catalogs, manage orders, and synchronize inventory - all through a simple API connection. This guide walks you through setting up the integration so your app can interact with Shopify data.\n\n<Note>\nBefore you begin, you'll need a Shopify store (or Partner account with a development store) and admin access to install apps and generate API credentials.\n</Note>\n\n## Prerequisites\n\n- A Shopify store or development store\n- Admin permissions to install apps and manage API credentials\n- An active Emergent project where you want to add Shopify functionality\n\n## Setup process\n\n<Steps>\n\n<Step title=\"Log in to Shopify\">\n\nGo to [**https://dev.shopify.com**](https://dev.shopify.com) (or [partners.shopify.com](http://partners.shopify.com)) and sign in to your account/organization.\n\n</Step>\n\n<Step title=\"Create a Shopify app\">\n\n1. In the left sidebar, click **Apps** → **Create app** → **Build from scratch**\n2. Enter an app name (e.g., \"Catalog Manager\")\n3. Click **Create**\n\n</Step>\n\n<Step title=\"Configure Admin API scopes\">\n\nIn your app:\n\n1. Open **Configuration** (or **API access**)\n2. Under **Admin API access scopes**, enable the scopes your integration requires (for example, `write_products`, `read_products`, `read_orders`, `write_orders`, `read_inventory`, `write_inventory`)\n3. Click **Save**\n4. **Release the app version**\n\n</Step>\n\n<Step title=\"Install the app on a store\">\n\n1. Open your app and find **Install** (or the **Installs** section)\n2. Click **Select store to install**\n3. Choose your development store and click **Install**\n4. Confirm that the app has been installed successfully\n\n</Step>\n\n<Step title=\"Retrieve your Client ID and Secret\">\n\nAfter installing the app:\n\n1. Go to your app's **Settings** → **API credentials** (or **Client credentials**)\n2. Copy the **Client ID**\n3. Copy the **Client Secret**\n\n</Step>\n\n<Step title=\"Get the store domain\">\n\n1. Go to Shopify Admin and open your store\n2. Look at the browser URL: `admin.shopify.com/store/HANDLE`\n3. Your Shopify store domain is `HANDLE.myshopify.com`\n\nYou will need the **Client ID, Client Secret, and store domain** for the integration.\n\n</Step>\n\n<Step title=\"Test the connection\">\n\nVerify the integration by describing a simple query to Emergent:\n\n> \"Fetch the first 10 products from my Shopify store and display their titles and prices.\"\n\nEmergent will generate code that uses the Shopify API to retrieve products. If the connection is successful, you'll see product data in your app.\n\n</Step>\n\n</Steps>\n\n## Common use cases\n\n<CardGroup cols={2}>\n\n<Card title=\"Product catalog sync\" icon=\"box\">\nDisplay your Shopify inventory in a custom storefront or mobile app\n</Card>\n\n<Card title=\"Order management\" icon=\"receipt\">\nCreate, update, and track orders programmatically\n</Card>\n\n<Card title=\"Inventory monitoring\" icon=\"warehouse\">\nReal-time stock level checks and low-inventory alerts\n</Card>\n\n<Card title=\"Customer data\" icon=\"users\">\nRetrieve customer profiles, order histories, and preferences\n</Card>\n\n</CardGroup>\n\n## API rate limits\n\nShopify enforces rate limits on API calls to protect store performance. The standard REST Admin API allows:\n\n- **2 requests per second** for most endpoints\n- **4 requests per second** for GraphQL (with cost-based throttling)\n\n<Warning>\nIf your app exceeds rate limits, Shopify will return `429 Too Many Requests` errors. Build in exponential backoff and respect the `Retry-After` header in responses.\n</Warning>\n\n<Note>\nEach Shopify playbook run costs approximately ~1.5 credits.\n</Note>\n\n## Webhooks for real-time updates (Optional)\n\nInstead of polling Shopify for changes, register webhooks to receive instant notifications when products, orders, or inventory change:\n\n1. In your Shopify app settings, go to **Webhooks**\n2. Click **Create webhook**\n3. Select the event (e.g., `products/update`, `orders/create`)\n4. Enter your Emergent app's webhook endpoint URL\n5. Click **Save**\n\nEmergent can generate webhook handlers that parse and store incoming Shopify events.\n\n<Tip>\nDescribe your webhook requirements in chat - Emergent will set up the endpoint, parse the payload, and help you store or act on the data.\n</Tip>\n\n## Troubleshooting\n\n| Issue | Solution |\n| --- | --- |\n| API credentials not working | Verify the Client ID and Client Secret were copied correctly (no extra spaces) - Confirm the app is installed on the correct store - Check that required API scopes are enabled in the app configuration - Regenerate credentials if you suspect they were compromised |\n| Missing product data | Ensure `read_products` scope is granted - Verify products are published to the sales channel your app is accessing - Check that you're querying the correct store (if you have multiple) |\n| Orders not appearing | Ensure the `read_all_orders` scope is granted in your custom app configuration |\n| Rate limit errors | Implement exponential backoff in your request logic - Cache frequently accessed data to reduce API calls - Consider switching to GraphQL for more efficient bulk queries |\n\n## Additional resources\n\n- [Shopify Admin API documentation](https://shopify.dev/docs/api/admin)\n- [Shopify GraphQL reference](https://shopify.dev/docs/api/admin-graphql)\n- [Webhook event reference](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook)\n\n<Tip>\nOnce your Shopify integration is live, you can expand it by asking Emergent to \"add a product search feature\" or \"create a dashboard showing today's orders\" - the AI will build on your existing Shopify connection.\n</Tip>","published_title":"Shopify","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"8fe604aa-44a8-419b-a272-9a093df91026","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Design inconsistencies","slug":"design-inconsistencies","content":"## Overview\n\nDesign inconsistencies - misaligned elements, inconsistent spacing, broken layouts on different screen sizes - are common when building visually complex apps. Emergent's agents can fix these issues when you describe what's wrong or share a screenshot.\n\nThe agent has full access to your app's design system, components, and styling. Treating it as a collaborative designer usually resolves issues faster than trying to edit code manually.\n\n## Common design issues\n\n### Layout breaks on mobile or desktop\n\nIf your app looks correct on one screen size but broken on another, describe the problem in chat:\n\n- \"The sidebar overlaps content on mobile\"\n- \"Cards stack vertically on desktop - they should be in a grid\"\n- \"Navigation menu doesn't collapse on small screens\"\n\nThe agent will adjust responsive breakpoints, Flexbox/Grid rules, or component variants.\n\n<Tip>\nAttach a screenshot showing the broken layout. Visual context helps the agent diagnose faster.\n</Tip>\n\n### Inconsistent spacing or alignment\n\nSpacing drift happens when components use hard-coded margins instead of design tokens. Tell the agent:\n\n- \"Button spacing is uneven across pages\"\n- \"Card padding looks different in the dashboard vs. settings\"\n- \"Headings don't align with the left edge of content\"\n\nThe agent will normalize spacing using your design system's tokens (`spacing-4`, `gap-md`, etc.) or create them if missing.\n\n### Colors or fonts don't match the design\n\nIf brand colors, typography, or button styles vary:\n\n- \"Primary button color is inconsistent - some are blue, some teal\"\n- \"Headings use different fonts on different pages\"\n- \"This section should use the brand green, not gray\"\n\nThe agent will update components to reference theme variables and ensure consistency.\n\n<Note>\nIf you haven't defined a design system yet, ask the agent to create one: \"Set up a design system with our brand colors and typography.\"\n</Note>\n\n### Elements overlap or have incorrect z-index\n\nOverlapping modals, dropdowns hidden behind other elements, or fixed headers covering content are z-index issues. Describe what you see:\n\n- \"The dropdown menu appears behind the modal backdrop\"\n- \"Fixed header covers the top of the page content\"\n- \"Tooltip is cut off by the card container\"\n\nThe agent will adjust stacking contexts and `z-index` values.\n\n### Images or icons are missing, broken, or incorrectly sized\n\nIf assets don't display properly:\n\n- \"Profile images are stretched/squashed\"\n- \"Icons are too large in the navigation\"\n- \"Hero image doesn't load\"\n\nThe agent can fix aspect ratios, apply `object-fit`, update icon sizing, or swap placeholder URLs for working assets.\n\n## How to report design issues\n\n<Steps>\n<Step title=\"Describe the issue clearly\">\nUse plain language: \"The login form is off-center on desktop\" or \"Button text is cut off on mobile.\"\n</Step>\n\n<Step title=\"Share a screenshot or screen recording\">\nAttach an image showing the problem. Highlight the affected area if helpful. The agent's vision capability processes screenshots directly.\n</Step>\n\n<Step title=\"Specify the page or component\">\nIf the issue is localized: \"This happens on the `/dashboard` page\" or \"Only in the `UserCard` component.\"\n</Step>\n\n<Step title=\"Mention the device/viewport if relevant\">\n\"This only happens on mobile\" or \"Broken in Safari, fine in Chrome.\"\n</Step>\n</Steps>\n\nThe agent will propose a fix, update the code, and you'll see changes in the preview immediately. To push those changes to your live app, publish explicitly using the Publish/Re-publish button.\n\n<Tip title=\"Use comparisons\">\n\"Make the spacing match the homepage\" or \"This card should look like the one in the sidebar\" helps the agent match existing patterns.\n</Tip>\n\n## Preventing design drift\n\n### Request a design system early\n\nAsk the agent to scaffold a design system with reusable tokens for colors, typography, spacing, and shadows:\n\n```\n\"Create a design system with our brand colors (primary: #3B82F6, secondary: #10B981) and consistent spacing.\"\n```\n\nThe agent will generate theme files and apply them across components.\n\n### Use design system tokens consistently\n\nWhen requesting new features, reference the design system:\n\n- \"Use `primary-600` for the button background\"\n- \"Apply `spacing-lg` between sections\"\n\nThis keeps styling predictable.\n\n### Review on multiple viewports\n\nEmergent's preview updates in real time. Test your app at different screen sizes (rclick the icon on the preview pane or open the live URL on your phone). Report layout issues as you spot them.\n\n<Info>\n\nThe workspace preview pane supports responsive resizing. Click the icon to simulate mobile, tablet, and desktop viewports.\n</Info>\n\n### Consolidate one-off styles\n\nIf you notice repeated custom styles (\"This heading is bold and 24px in three places\"), ask the agent to extract a reusable component or style:\n\n```\n\"Create a `SectionHeading` component for these repeated bold 24px headings.\"\n```\n\n## When to escalate\n\nMost design issues resolve with a chat message and optional screenshot. If the agent's fix doesn't work after 2-3 attempts:\n\n- Describe what changed and what's still broken\n- Share before/after screenshots\n- Ask the agent to explain its approach: \"Why is this element still misaligned?\"\n\nThe agent can reason through CSS specificity conflicts, framework quirks, or inherited styles.\n\n<Warning>\nAvoid editing generated CSS or component files directly in the code editor unless you're experienced with the framework. Manual edits can conflict with the agent's changes and create merge issues.\n</Warning>\n\n## Related resources\n\n<CardGroup cols={2}>\n<Card title=\"Workspace tour\" icon=\"compass\" href=\"/a-tour-of-the-workspace\">\nLearn how to use the preview pane and inspect design changes\n</Card>\n<Card title=\"Web to Mobile conversion\" icon=\"mobile\" href=\"/web-mobile-conversion-canonical\">\nAdapt designs for different platforms\n</Card>\n<Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\nUnderstand design system, tokens, and other Emergent terms\n</Card>\n</CardGroup>","order":88,"parent_id":null,"icon":"palette","description":"Fixing common design/layout issues via the agent.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:28.530265+00:00","published_at":"2026-09-22T06:19:28.530265+00:00","published_content":"## Overview\n\nDesign inconsistencies - misaligned elements, inconsistent spacing, broken layouts on different screen sizes - are common when building visually complex apps. Emergent's agents can fix these issues when you describe what's wrong or share a screenshot.\n\nThe agent has full access to your app's design system, components, and styling. Treating it as a collaborative designer usually resolves issues faster than trying to edit code manually.\n\n## Common design issues\n\n### Layout breaks on mobile or desktop\n\nIf your app looks correct on one screen size but broken on another, describe the problem in chat:\n\n- \"The sidebar overlaps content on mobile\"\n- \"Cards stack vertically on desktop - they should be in a grid\"\n- \"Navigation menu doesn't collapse on small screens\"\n\nThe agent will adjust responsive breakpoints, Flexbox/Grid rules, or component variants.\n\n<Tip>\nAttach a screenshot showing the broken layout. Visual context helps the agent diagnose faster.\n</Tip>\n\n### Inconsistent spacing or alignment\n\nSpacing drift happens when components use hard-coded margins instead of design tokens. Tell the agent:\n\n- \"Button spacing is uneven across pages\"\n- \"Card padding looks different in the dashboard vs. settings\"\n- \"Headings don't align with the left edge of content\"\n\nThe agent will normalize spacing using your design system's tokens (`spacing-4`, `gap-md`, etc.) or create them if missing.\n\n### Colors or fonts don't match the design\n\nIf brand colors, typography, or button styles vary:\n\n- \"Primary button color is inconsistent - some are blue, some teal\"\n- \"Headings use different fonts on different pages\"\n- \"This section should use the brand green, not gray\"\n\nThe agent will update components to reference theme variables and ensure consistency.\n\n<Note>\nIf you haven't defined a design system yet, ask the agent to create one: \"Set up a design system with our brand colors and typography.\"\n</Note>\n\n### Elements overlap or have incorrect z-index\n\nOverlapping modals, dropdowns hidden behind other elements, or fixed headers covering content are z-index issues. Describe what you see:\n\n- \"The dropdown menu appears behind the modal backdrop\"\n- \"Fixed header covers the top of the page content\"\n- \"Tooltip is cut off by the card container\"\n\nThe agent will adjust stacking contexts and `z-index` values.\n\n### Images or icons are missing, broken, or incorrectly sized\n\nIf assets don't display properly:\n\n- \"Profile images are stretched/squashed\"\n- \"Icons are too large in the navigation\"\n- \"Hero image doesn't load\"\n\nThe agent can fix aspect ratios, apply `object-fit`, update icon sizing, or swap placeholder URLs for working assets.\n\n## How to report design issues\n\n<Steps>\n<Step title=\"Describe the issue clearly\">\nUse plain language: \"The login form is off-center on desktop\" or \"Button text is cut off on mobile.\"\n</Step>\n\n<Step title=\"Share a screenshot or screen recording\">\nAttach an image showing the problem. Highlight the affected area if helpful. The agent's vision capability processes screenshots directly.\n</Step>\n\n<Step title=\"Specify the page or component\">\nIf the issue is localized: \"This happens on the `/dashboard` page\" or \"Only in the `UserCard` component.\"\n</Step>\n\n<Step title=\"Mention the device/viewport if relevant\">\n\"This only happens on mobile\" or \"Broken in Safari, fine in Chrome.\"\n</Step>\n</Steps>\n\nThe agent will propose a fix, update the code, and you'll see changes in the preview immediately. To push those changes to your live app, publish explicitly using the Publish/Re-publish button.\n\n<Tip title=\"Use comparisons\">\n\"Make the spacing match the homepage\" or \"This card should look like the one in the sidebar\" helps the agent match existing patterns.\n</Tip>\n\n## Preventing design drift\n\n### Request a design system early\n\nAsk the agent to scaffold a design system with reusable tokens for colors, typography, spacing, and shadows:\n\n```\n\"Create a design system with our brand colors (primary: #3B82F6, secondary: #10B981) and consistent spacing.\"\n```\n\nThe agent will generate theme files and apply them across components.\n\n### Use design system tokens consistently\n\nWhen requesting new features, reference the design system:\n\n- \"Use `primary-600` for the button background\"\n- \"Apply `spacing-lg` between sections\"\n\nThis keeps styling predictable.\n\n### Review on multiple viewports\n\nEmergent's preview updates in real time. Test your app at different screen sizes (rclick the icon on the preview pane or open the live URL on your phone). Report layout issues as you spot them.\n\n<Info>\n\nThe workspace preview pane supports responsive resizing. Click the icon to simulate mobile, tablet, and desktop viewports.\n</Info>\n\n### Consolidate one-off styles\n\nIf you notice repeated custom styles (\"This heading is bold and 24px in three places\"), ask the agent to extract a reusable component or style:\n\n```\n\"Create a `SectionHeading` component for these repeated bold 24px headings.\"\n```\n\n## When to escalate\n\nMost design issues resolve with a chat message and optional screenshot. If the agent's fix doesn't work after 2-3 attempts:\n\n- Describe what changed and what's still broken\n- Share before/after screenshots\n- Ask the agent to explain its approach: \"Why is this element still misaligned?\"\n\nThe agent can reason through CSS specificity conflicts, framework quirks, or inherited styles.\n\n<Warning>\nAvoid editing generated CSS or component files directly in the code editor unless you're experienced with the framework. Manual edits can conflict with the agent's changes and create merge issues.\n</Warning>\n\n## Related resources\n\n<CardGroup cols={2}>\n<Card title=\"Workspace tour\" icon=\"compass\" href=\"/a-tour-of-the-workspace\">\nLearn how to use the preview pane and inspect design changes\n</Card>\n<Card title=\"Web to Mobile conversion\" icon=\"mobile\" href=\"/web-mobile-conversion-canonical\">\nAdapt designs for different platforms\n</Card>\n<Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\nUnderstand design system, tokens, and other Emergent terms\n</Card>\n</CardGroup>","published_title":"Design inconsistencies","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"7ee51f16-92e7-4457-b879-6491f84c7baf","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Missing functionality","slug":"missing-functionality","content":"## Overview\n\nWhen a feature you described doesn't appear in your app - or doesn't work as expected - it's usually due to one of a few common causes. This page walks you through diagnosing the issue and requesting a rebuild or clarification.\n\n<Note>\nMost missing functionality is resolved by rephrasing your request or explicitly calling out the feature in a follow-up chat message.\n</Note>\n\n---\n\n## Common reasons features go missing\n\nThe agent misunderstood the scope\nNatural language can be ambiguous. If you said \"add user profiles,\" the agent might have built a basic profile page but skipped avatar uploads, bio fields, or edit functionality.\n\n**The feature was deprioritized**\nEmergent's agents prioritize core flows first. Secondary features - like admin dashboards, analytics, or \"nice-to-have\" UI polish - may be deferred or omitted if the initial build focused on MVP functionality.\n\n**A dependency wasn't clear**\nSome features require scaffolding. For example, \"send email notifications\" needs an email service integrated, and \"save preferences\" needs a database schema. If you didn't mention the underlying requirement, the agent may have skipped the feature.\n\nThe feature exists but isn't visible\nCheck that you're testing the right screen, user role, or device form factor. A feature built for mobile may not render on desktop, or an admin-only button may be hidden for regular users.\n\n---\n\n## Step-by-step diagnosis\n\n<Steps>\n\n<Step title=\"Verify the feature was in scope\">\nRe-read your original chat prompt and any follow-up messages. Did you explicitly request the feature, or was it implied? Agents work best with direct, specific instructions.\n</Step>\n\n<Step title=\"Check the current build\">\nOpen the live preview or published app and navigate to where the feature should appear. Test all relevant user roles, screen sizes, and edge cases (e.g., empty states, logged-out views).\n</Step>\n\n<Step title=\"Review the build log (if available)\">\nSome workspaces surface build summaries or agent notes in the chat history. Look for messages like \"skipped X due to Y\" or \"deferred Z for next iteration.\"\n</Step>\n\n<Step title=\"Search the codebase\">\nUse the workspace file tree or search to look for related code. Note that the code editor (including the file tree) is available on all plans including Free; only GitHub push requires Standard+. If the feature is partially implemented - like a backend route without a UI - you'll find clues in `api/`, `components/`, or `pages/` directories.\n</Step>\n\n</Steps>\n\n---\n\n## Requesting a fix or rebuild\n\nOnce you've confirmed the feature is missing or incomplete, ask the agent to build it in a new chat message. Use clear, actionable language:\n\n<CodeGroup>\n\n```plaintext Good example\nAdd a \"Save Draft\" button to the blog post editor.\nIt should save the current title and body to the\ndatabase without publishing. Show a success toast\nwhen saved.\n```\n\n```plaintext Avoid vague requests\nThe editor is missing stuff. Fix it.\n```\n\n</CodeGroup>\n\nBe explicit about acceptance criteria:\n\n- Where should the feature appear? (e.g., \"in the top-right of the editor header\")\n- What should it do? (e.g., \"POST to `/api/drafts`, store in MongoDB\")\n- What should the user see? (e.g., \"a green checkmark icon and 'Draft saved' message\")\n\n<Tip>\nIf the feature depends on a database collection, API endpoint, or third-party service, mention it up front. For example: \"Use the `drafts` collection in MongoDB\" or \"Integrate Stripe for payment processing.\"\n</Tip>\n\n---\n\n## When functionality is partially built\n\nSometimes a feature exists in the backend but lacks a UI, or vice versa. Here's how to complete it:\n\n| Situation | Next step |\n|-----------|-----------|\n| Backend route exists, no UI | \"Create a form in `components/DraftEditor.tsx` that calls `POST /api/drafts` and shows a success message.\" |\n| UI exists, no backend | \"Implement the `/api/drafts` endpoint: accept title and body, save to MongoDB `drafts` collection, return 201.\" |\n| Feature works on web, missing on mobile | \"Add the Save Draft button to the mobile layout in `DraftEditor.tsx`. It should match the web behavior.\" |\n\n---\n\n## Common gotchas\n\n<AccordionGroup>\n\n<Accordion title=\"Feature was removed in a later iteration\">\nIf you asked the agent to \"simplify\" or \"redesign\" the app, it may have removed features you wanted to keep. Check the chat history for messages like \"removed X to simplify Y.\"\n\n**Fix:** Explicitly ask to restore it: \"Bring back the Save Draft button and keep the new design for the rest of the editor.\"\n</Accordion>\n\n<Accordion title=\"Feature is hidden behind a feature flag or env var\">\nSome functionality - like admin panels or payment flows - may be gated by environment variables or user roles. Check your `.env` file (accessible via the VS Code editor, available on all plans) and any role-checking logic in the code.\n\n**Fix:** Update the relevant env var or user role in your database. See [Database (MongoDB)](/database-mongodb) for how to modify user records.\n</Accordion>\n\n<Accordion title=\"Third-party service not configured\">\nFeatures like email, payments, or SMS require API keys and service setup. If the agent built the integration but you haven't added credentials, the feature will fail silently.\n\n**Fix:** Add the missing API key to your `.env` file or workspace secrets. See [The Universal LLM Key](/the-universal-llm-key) for an example of secret configuration.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Escalation\n\nIf you've followed the steps above and the feature still doesn't work:\n\n1. **Describe the exact behavior** you're seeing (e.g., \"clicking Save Draft shows a 500 error in the console\").\n2. **Share the expected behavior** (e.g., \"it should save to MongoDB and show a success toast\").\n3. **Ask the agent to debug:** \"Check the `/api/drafts` endpoint and the `DraftEditor` component. The save button isn't working.\"\n\n<Warning>\nIf the agent repeatedly misunderstands or skips the same feature, try breaking the request into smaller, sequential steps. For example: \"First, create the database schema for drafts. Then, build the API endpoint. Finally, add the UI button.\"\n</Warning>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n\n<Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\nDefinitions of workspace, agent, build, and other platform terms\n</Card>\n\n<Card title=\"Tour of the workspace\" icon=\"map\" href=\"/a-tour-of-the-workspace\">\nUnderstand where code, logs, and builds live in your project\n</Card>\n\n</CardGroup>","order":89,"parent_id":null,"icon":"puzzle","description":"Diagnosing and requesting a feature that's missing or didn't build as expected.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:29.662494+00:00","published_at":"2026-09-22T06:19:29.662494+00:00","published_content":"## Overview\n\nWhen a feature you described doesn't appear in your app - or doesn't work as expected - it's usually due to one of a few common causes. This page walks you through diagnosing the issue and requesting a rebuild or clarification.\n\n<Note>\nMost missing functionality is resolved by rephrasing your request or explicitly calling out the feature in a follow-up chat message.\n</Note>\n\n---\n\n## Common reasons features go missing\n\nThe agent misunderstood the scope\nNatural language can be ambiguous. If you said \"add user profiles,\" the agent might have built a basic profile page but skipped avatar uploads, bio fields, or edit functionality.\n\n**The feature was deprioritized**\nEmergent's agents prioritize core flows first. Secondary features - like admin dashboards, analytics, or \"nice-to-have\" UI polish - may be deferred or omitted if the initial build focused on MVP functionality.\n\n**A dependency wasn't clear**\nSome features require scaffolding. For example, \"send email notifications\" needs an email service integrated, and \"save preferences\" needs a database schema. If you didn't mention the underlying requirement, the agent may have skipped the feature.\n\nThe feature exists but isn't visible\nCheck that you're testing the right screen, user role, or device form factor. A feature built for mobile may not render on desktop, or an admin-only button may be hidden for regular users.\n\n---\n\n## Step-by-step diagnosis\n\n<Steps>\n\n<Step title=\"Verify the feature was in scope\">\nRe-read your original chat prompt and any follow-up messages. Did you explicitly request the feature, or was it implied? Agents work best with direct, specific instructions.\n</Step>\n\n<Step title=\"Check the current build\">\nOpen the live preview or published app and navigate to where the feature should appear. Test all relevant user roles, screen sizes, and edge cases (e.g., empty states, logged-out views).\n</Step>\n\n<Step title=\"Review the build log (if available)\">\nSome workspaces surface build summaries or agent notes in the chat history. Look for messages like \"skipped X due to Y\" or \"deferred Z for next iteration.\"\n</Step>\n\n<Step title=\"Search the codebase\">\nUse the workspace file tree or search to look for related code. Note that the code editor (including the file tree) is available on all plans including Free; only GitHub push requires Standard+. If the feature is partially implemented - like a backend route without a UI - you'll find clues in `api/`, `components/`, or `pages/` directories.\n</Step>\n\n</Steps>\n\n---\n\n## Requesting a fix or rebuild\n\nOnce you've confirmed the feature is missing or incomplete, ask the agent to build it in a new chat message. Use clear, actionable language:\n\n<CodeGroup>\n\n```plaintext Good example\nAdd a \"Save Draft\" button to the blog post editor.\nIt should save the current title and body to the\ndatabase without publishing. Show a success toast\nwhen saved.\n```\n\n```plaintext Avoid vague requests\nThe editor is missing stuff. Fix it.\n```\n\n</CodeGroup>\n\nBe explicit about acceptance criteria:\n\n- Where should the feature appear? (e.g., \"in the top-right of the editor header\")\n- What should it do? (e.g., \"POST to `/api/drafts`, store in MongoDB\")\n- What should the user see? (e.g., \"a green checkmark icon and 'Draft saved' message\")\n\n<Tip>\nIf the feature depends on a database collection, API endpoint, or third-party service, mention it up front. For example: \"Use the `drafts` collection in MongoDB\" or \"Integrate Stripe for payment processing.\"\n</Tip>\n\n---\n\n## When functionality is partially built\n\nSometimes a feature exists in the backend but lacks a UI, or vice versa. Here's how to complete it:\n\n| Situation | Next step |\n|-----------|-----------|\n| Backend route exists, no UI | \"Create a form in `components/DraftEditor.tsx` that calls `POST /api/drafts` and shows a success message.\" |\n| UI exists, no backend | \"Implement the `/api/drafts` endpoint: accept title and body, save to MongoDB `drafts` collection, return 201.\" |\n| Feature works on web, missing on mobile | \"Add the Save Draft button to the mobile layout in `DraftEditor.tsx`. It should match the web behavior.\" |\n\n---\n\n## Common gotchas\n\n<AccordionGroup>\n\n<Accordion title=\"Feature was removed in a later iteration\">\nIf you asked the agent to \"simplify\" or \"redesign\" the app, it may have removed features you wanted to keep. Check the chat history for messages like \"removed X to simplify Y.\"\n\n**Fix:** Explicitly ask to restore it: \"Bring back the Save Draft button and keep the new design for the rest of the editor.\"\n</Accordion>\n\n<Accordion title=\"Feature is hidden behind a feature flag or env var\">\nSome functionality - like admin panels or payment flows - may be gated by environment variables or user roles. Check your `.env` file (accessible via the VS Code editor, available on all plans) and any role-checking logic in the code.\n\n**Fix:** Update the relevant env var or user role in your database. See [Database (MongoDB)](/database-mongodb) for how to modify user records.\n</Accordion>\n\n<Accordion title=\"Third-party service not configured\">\nFeatures like email, payments, or SMS require API keys and service setup. If the agent built the integration but you haven't added credentials, the feature will fail silently.\n\n**Fix:** Add the missing API key to your `.env` file or workspace secrets. See [The Universal LLM Key](/the-universal-llm-key) for an example of secret configuration.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n## Escalation\n\nIf you've followed the steps above and the feature still doesn't work:\n\n1. **Describe the exact behavior** you're seeing (e.g., \"clicking Save Draft shows a 500 error in the console\").\n2. **Share the expected behavior** (e.g., \"it should save to MongoDB and show a success toast\").\n3. **Ask the agent to debug:** \"Check the `/api/drafts` endpoint and the `DraftEditor` component. The save button isn't working.\"\n\n<Warning>\nIf the agent repeatedly misunderstands or skips the same feature, try breaking the request into smaller, sequential steps. For example: \"First, create the database schema for drafts. Then, build the API endpoint. Finally, add the UI button.\"\n</Warning>\n\n---\n\n## Related pages\n\n<CardGroup cols={2}>\n\n<Card title=\"Glossary\" icon=\"book\" href=\"/glossary-of-emergent-terms\">\nDefinitions of workspace, agent, build, and other platform terms\n</Card>\n\n<Card title=\"Tour of the workspace\" icon=\"map\" href=\"/a-tour-of-the-workspace\">\nUnderstand where code, logs, and builds live in your project\n</Card>\n\n</CardGroup>","published_title":"Missing functionality","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"ee2c74e3-7d38-43c1-8bb8-88f025811b05","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing issues","slug":"deployment-issues","content":"## Overview\n\nPublishing issues fall into two broad categories: **build-time failures (the agent cannot bundle or prepare your app) and runtime failures** (your app starts but behaves incorrectly or crashes). This page walks through the most common scenarios and how to resolve them.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n<Callout type=\"tip\" title=\"Check the publishing pipeline first\">\nMost build errors appear in the **publishing pipeline log**. See [Publishing pipeline failures](/deployment-pipeline-failures) for step-by-step diagnostics.\n</Callout>\n\n---\n\n## Build-time failures\n\n### Missing dependencies\n\n**Symptom:** Build fails with `Module not found` or `Cannot find package`.\n\n**Cause:** The agent has not added a required library to `package.json` (Node.js), `requirements.txt` (Python), or your framework's manifest.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Identify the missing package\">\nRead the build log; the error message names the import that failed.\n</Step>\n\n<Step title=\"Tell the agent in chat\">\n\"Install `[package-name]` and re‑publish.\" The agent will add the dependency and trigger a new build.\n</Step>\n\n<Step title=\"Verify the manifest\">\nIn the **Files** pane, confirm the package appears in `package.json` or `requirements.txt` before the next published app.\n</Step>\n</Steps>\n\n---\n\n### Incompatible Node / Python version\n\n**Symptom:** Build fails with syntax errors or a message like `Unexpected token` (Node) or `invalid syntax` (Python).\n\n**Cause:** The published app runtime uses a different language version than the code expects (for example, async/await syntax in Node 12, or Python 3.11 match statements on a Python 3.9 runtime).\n\n**Fix:**\n\n1. Check the [Publishing types](/deployment-types) page for the runtime version your plan provides.\n2. Ask the agent: *\"Use syntax compatible with Node 16\"* (or the version you have).\n3. Re‑generate the code and re‑publish.\n\n<Callout type=\"info\">\nIf you need a specific runtime version, consider upgrading your [Publishing plan level](/deployment-plan-levels) or switching to a Docker‑based published app (if available on your plan).\n</Callout>\n\n---\n\n### Build timeout\n\n**Symptom:** Build aborts with `Timeout exceeded` or `Build killed`.\n\n**Cause:** The build step (install dependencies, transpile, bundle) runs longer than the time limit for your plan.\n\n**Fix:**\n\n<Tabs>\n<Tab title=\"Reduce dependencies\">\nAsk the agent to remove unused libraries or combine smaller packages. Fewer dependencies = faster install.\n</Tab>\n\n<Tab title=\"Optimize build config\">\nFor Next.js or Vite apps, disable source maps in production or switch to a lighter bundler mode. Example: *\"Set `productionBrowserSourceMaps: false` in `next.config.js`.\"*\n</Tab>\n\n<Tab title=\"Upgrade plan\">\nHigher [Publishing plan levels](/deployment-plan-levels) offer longer build windows and more CPU.\n</Tab>\n</Tabs>\n\n---\n\n### Out of memory during build\n\n**Symptom:** Build crashes with `JavaScript heap out of memory` or `Killed`.\n\n**Cause:** The build process (Webpack, Vite, TypeScript compiler) exceeds available RAM.\n\n**Fix:**\n\n- **Node apps:** Add `NODE_OPTIONS=--max-old-space-size=4096` to your build environment (ask the agent to set this in the publish config).\n- **Simplify the build:** Split large bundles, enable tree‑shaking, or lazy‑load heavy modules.\n- **Upgrade plan:** More RAM is available at higher tiers - see [Publishing plan levels](/deployment-plan-levels).\n\n---\n\n## Runtime failures\n\n### App starts but shows a blank page\n\n**Symptom:** Published app succeeds; opening the URL displays a white screen or \"Application error.\"\n\n**Common causes & fixes:**\n\n| Cause | How to diagnose | Fix |\n|-------|-----------------|-----|\n| Client‑side crash | Open browser DevTools → Console; look for uncaught exceptions. | Share the error with the agent: *\"Fix runtime error: [paste stack trace].\"* |\n| Missing environment variable | App tries to read `process.env.API_KEY` but it's undefined. | Set the variable in the **Secrets** tab and re‑publish. See [How apps work here](/how-apps-work-here-mental-model#environment-variables). |\n| Static‑asset 404 | CSS or JS files return 404; check Network tab in DevTools. | Ask the agent to fix the public path or output directory in the build config. |\n\n---\n\n### Database connection failures\n\n**Symptom:** Logs show `MongoNetworkError`, `ECONNREFUSED`, or similar.\n\n**Cause:** The app cannot reach the MongoDB instance - wrong connection string, firewall rule, or the database is not provisioned.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Verify the database is provisioned\">\nConfirm your app has a MongoDB database - check in the **Database** panel in the **Manage Publishing** panel( click **Re-publish** to open) or ask the agent: *\"Does this app have a database?\"* If not, ask: *\"Add a MongoDB database to this project.\"*\n</Step>\n\n<Step title=\"Check the connection string\">\nThe environment variable (`MONGO_URL` or `DB_NAME`) must match the value shown in the **Secrets** tab (under **Preview → Manage → Secrets**). Copy it exactly - include username, password, and database name.\n</Step>\n\n<Step title=\"Whitelist the published app IP\">\nEmergent publishes from fixed egress IPs. If your MongoDB host has an IP allowlist, retrieve the current IP list from **app.emergent.sh/ip-addresses** and add those addresses.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Credentials in code\">\nNever hard‑code `mongodb://user:pass@host` in your source files. Always use environment variables and keep secrets out of version control.\n</Callout>\n\nRead more: [Database (MongoDB)](/database-mongodb).\n\n---\n\n### API or external service timeouts\n\n**Symptom:** Requests to third‑party APIs (Stripe, OpenAI, etc.) hang or return `504 Gateway Timeout`.\n\n**Possible causes:**\n\n- **Rate limit:** Your API key has hit a quota.\n- **Network policy:** The publish environment blocks outbound HTTPS to certain domains (rare).\n- **Slow endpoint:** The third‑party service is down or experiencing latency.\n\n**Fix:**\n\n1. **Check the third‑party status page** (e.g., `status.openai.com`).\n2. **Increase timeout** in your HTTP client (Axios, Fetch): set `timeout: 30000` (30 seconds).\n3. **Verify API key:** Confirm the key is valid and has sufficient quota; test it locally or in a tool like Postman.\n4. **Review logs:** Look for `429 Too Many Requests` or `401 Unauthorized` - these point to credential or quota issues, not network problems.\n\n---\n\n### Published app health check fails\n\n**Symptom: Publishing pipeline succeeds, but the platform marks the app as unhealthy** and does not route traffic.\n\n**Cause:** The health‑check endpoint (`/health`) does not return the required status within the timeout window. The platform checks for an HTTP 200 response on the frontend and a response with status < 500 on the backend at `/health`, with a fixed 10-second timeout and 3 retries (20-second interval).\n\n**Fix:**\n\n- **Add or fix the health route:** Ensure your app responds to `GET /health` with a 200 status (frontend) or any status below 500 (backend), with minimal logic (e.g., `res.json({ status: 'ok' })`).\n- **Speed up startup:** Move heavy initialization (database seeding, large file reads) out of the main server bootstrap so the health check can succeed quickly.\n\n---\n\n### Custom domain not resolving\n\n**Symptom:** Visiting `app.yourdomain.com` shows a DNS error or \"Site not found.\"\n\n**Diagnosis:**\n\n<Steps>\n<Step title=\"Verify DNS records\">\nRun `dig yourdomain.com` or use an online DNS checker. For the root domain, you must have **two A records pointing to 162.159.142.117 and 172.66.2.113**. For `www`, add a CNAME pointing to your production hostname. Do not use a CNAME for the root domain, and never point records to a preview URL.\n</Step>\n\n<Step title=\"Wait for propagation\">\nDNS changes can take 1-48 hours to propagate globally. Test from multiple locations or use `8.8.8.8` as your resolver.\n</Step>\n\n<Step title=\"Check SSL certificate status\">\nIn the workspace, navigate to **Preview → Manage → Domain** → Check Status** and confirm the SSL certificate shows **Active-Verified**. If it shows **Pending**, wait a few more minutes; if **Failed**, double‑check your DNS records.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nDetailed setup instructions: [Custom domain](/custom-domain).\n</Callout>\n\n---\n\n## Out of credits / quota exceeded\n\n**Symptom:** Published app is rejected with `INSUFFICIENT_CREDITS`, or aborts with *\"Insufficient credits.\"* Note that live apps can still re-publish at a low balance; new published versions require a minimum credit threshold.\n\n**Cause:** Your account has consumed its [credit allocation](/managing-credit-usage) for builds, compute time, or API calls.\n\n**Fix:**\n\n- **Check your balance:** Open the **Billing** or **Usage** dashboard (depending on your plan).\n- **Upgrade or top up:** Purchase additional credits or move to a higher plan tier with more monthly allowance.\n- **Optimize usage:** Reduce the number of published versions by batching changes; use preview builds sparingly.\n\n---\n\n## Image / video / audio generation failures\n\n**Symptom:** AI‑generated media assets fail to appear or return errors.\n\n**Cause:** Model unavailable, quota exceeded, or unsupported parameters.\n\n**Fix:** See the dedicated page [AI media generation](/ai-media-generation-image-video-audio) for model‑specific troubleshooting and parameter guidance.\n\n---\n\n## Getting further help\n\nIf none of the above resolves your issue:\n\n<CardGroup cols={2}>\n<Card title=\"Ask the agent\" icon=\"message-circle\">\nPaste the full error message into chat. The agent can read logs and often auto‑fix configuration mistakes.\n</Card>\n\n<Card title=\"Review the pipeline log\" icon=\"list\" href=\"/published app-pipeline-failures\">\nStep‑by‑step guide to interpreting build and publish logs.\n</Card>\n\n<Card title=\"Check platform status\" icon=\"activity\">\nRare outages or maintenance windows are announced on the Emergent status page (link in your workspace footer).\n</Card>\n\n<Card title=\"Contact support\" icon=\"life-buoy\">\nUse the **Help** button in the workspace to open a ticket. Include your project ID and the timestamp of the failed published app.\n</Card>\n</CardGroup>\n\n<Callout type=\"success\" title=\"Most issues resolve in chat\">\nThe agent has access to your publish logs and can iterate on fixes in real time - start there before opening a support ticket.\n</Callout>","order":90,"parent_id":null,"icon":"rocket","description":"Common deployment failures and how to fix them.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T10:29:46.594416+00:00","published_at":"2026-09-25T10:29:46.594416+00:00","published_content":"## Overview\n\nPublishing issues fall into two broad categories: **build-time failures (the agent cannot bundle or prepare your app) and runtime failures** (your app starts but behaves incorrectly or crashes). This page walks through the most common scenarios and how to resolve them.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n<Callout type=\"tip\" title=\"Check the publishing pipeline first\">\nMost build errors appear in the **publishing pipeline log**. See [Publishing pipeline failures](/deployment-pipeline-failures) for step-by-step diagnostics.\n</Callout>\n\n---\n\n## Build-time failures\n\n### Missing dependencies\n\n**Symptom:** Build fails with `Module not found` or `Cannot find package`.\n\n**Cause:** The agent has not added a required library to `package.json` (Node.js), `requirements.txt` (Python), or your framework's manifest.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Identify the missing package\">\nRead the build log; the error message names the import that failed.\n</Step>\n\n<Step title=\"Tell the agent in chat\">\n\"Install `[package-name]` and re‑publish.\" The agent will add the dependency and trigger a new build.\n</Step>\n\n<Step title=\"Verify the manifest\">\nIn the **Files** pane, confirm the package appears in `package.json` or `requirements.txt` before the next published app.\n</Step>\n</Steps>\n\n---\n\n### Incompatible Node / Python version\n\n**Symptom:** Build fails with syntax errors or a message like `Unexpected token` (Node) or `invalid syntax` (Python).\n\n**Cause:** The published app runtime uses a different language version than the code expects (for example, async/await syntax in Node 12, or Python 3.11 match statements on a Python 3.9 runtime).\n\n**Fix:**\n\n1. Check the [Publishing types](/deployment-types) page for the runtime version your plan provides.\n2. Ask the agent: *\"Use syntax compatible with Node 16\"* (or the version you have).\n3. Re‑generate the code and re‑publish.\n\n<Callout type=\"info\">\nIf you need a specific runtime version, consider upgrading your [Publishing plan level](/deployment-plan-levels) or switching to a Docker‑based published app (if available on your plan).\n</Callout>\n\n---\n\n### Build timeout\n\n**Symptom:** Build aborts with `Timeout exceeded` or `Build killed`.\n\n**Cause:** The build step (install dependencies, transpile, bundle) runs longer than the time limit for your plan.\n\n**Fix:**\n\n<Tabs>\n<Tab title=\"Reduce dependencies\">\nAsk the agent to remove unused libraries or combine smaller packages. Fewer dependencies = faster install.\n</Tab>\n\n<Tab title=\"Optimize build config\">\nFor Next.js or Vite apps, disable source maps in production or switch to a lighter bundler mode. Example: *\"Set `productionBrowserSourceMaps: false` in `next.config.js`.\"*\n</Tab>\n\n<Tab title=\"Upgrade plan\">\nHigher [Publishing plan levels](/deployment-plan-levels) offer longer build windows and more CPU.\n</Tab>\n</Tabs>\n\n---\n\n### Out of memory during build\n\n**Symptom:** Build crashes with `JavaScript heap out of memory` or `Killed`.\n\n**Cause:** The build process (Webpack, Vite, TypeScript compiler) exceeds available RAM.\n\n**Fix:**\n\n- **Node apps:** Add `NODE_OPTIONS=--max-old-space-size=4096` to your build environment (ask the agent to set this in the publish config).\n- **Simplify the build:** Split large bundles, enable tree‑shaking, or lazy‑load heavy modules.\n- **Upgrade plan:** More RAM is available at higher tiers - see [Publishing plan levels](/deployment-plan-levels).\n\n---\n\n## Runtime failures\n\n### App starts but shows a blank page\n\n**Symptom:** Published app succeeds; opening the URL displays a white screen or \"Application error.\"\n\n**Common causes & fixes:**\n\n| Cause | How to diagnose | Fix |\n|-------|-----------------|-----|\n| Client‑side crash | Open browser DevTools → Console; look for uncaught exceptions. | Share the error with the agent: *\"Fix runtime error: [paste stack trace].\"* |\n| Missing environment variable | App tries to read `process.env.API_KEY` but it's undefined. | Set the variable in the **Secrets** tab and re‑publish. See [How apps work here](/how-apps-work-here-mental-model#environment-variables). |\n| Static‑asset 404 | CSS or JS files return 404; check Network tab in DevTools. | Ask the agent to fix the public path or output directory in the build config. |\n\n---\n\n### Database connection failures\n\n**Symptom:** Logs show `MongoNetworkError`, `ECONNREFUSED`, or similar.\n\n**Cause:** The app cannot reach the MongoDB instance - wrong connection string, firewall rule, or the database is not provisioned.\n\n**Fix:**\n\n<Steps>\n<Step title=\"Verify the database is provisioned\">\nConfirm your app has a MongoDB database - check in the **Database** panel in the **Manage Publishing** panel( click **Re-publish** to open) or ask the agent: *\"Does this app have a database?\"* If not, ask: *\"Add a MongoDB database to this project.\"*\n</Step>\n\n<Step title=\"Check the connection string\">\nThe environment variable (`MONGO_URL` or `DB_NAME`) must match the value shown in the **Secrets** tab (under **Preview → Manage → Secrets**). Copy it exactly - include username, password, and database name.\n</Step>\n\n<Step title=\"Whitelist the published app IP\">\nEmergent publishes from fixed egress IPs. If your MongoDB host has an IP allowlist, retrieve the current IP list from **app.emergent.sh/ip-addresses** and add those addresses.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Credentials in code\">\nNever hard‑code `mongodb://user:pass@host` in your source files. Always use environment variables and keep secrets out of version control.\n</Callout>\n\nRead more: [Database (MongoDB)](/database-mongodb).\n\n---\n\n### API or external service timeouts\n\n**Symptom:** Requests to third‑party APIs (Stripe, OpenAI, etc.) hang or return `504 Gateway Timeout`.\n\n**Possible causes:**\n\n- **Rate limit:** Your API key has hit a quota.\n- **Network policy:** The publish environment blocks outbound HTTPS to certain domains (rare).\n- **Slow endpoint:** The third‑party service is down or experiencing latency.\n\n**Fix:**\n\n1. **Check the third‑party status page** (e.g., `status.openai.com`).\n2. **Increase timeout** in your HTTP client (Axios, Fetch): set `timeout: 30000` (30 seconds).\n3. **Verify API key:** Confirm the key is valid and has sufficient quota; test it locally or in a tool like Postman.\n4. **Review logs:** Look for `429 Too Many Requests` or `401 Unauthorized` - these point to credential or quota issues, not network problems.\n\n---\n\n### Published app health check fails\n\n**Symptom: Publishing pipeline succeeds, but the platform marks the app as unhealthy** and does not route traffic.\n\n**Cause:** The health‑check endpoint (`/health`) does not return the required status within the timeout window. The platform checks for an HTTP 200 response on the frontend and a response with status < 500 on the backend at `/health`, with a fixed 10-second timeout and 3 retries (20-second interval).\n\n**Fix:**\n\n- **Add or fix the health route:** Ensure your app responds to `GET /health` with a 200 status (frontend) or any status below 500 (backend), with minimal logic (e.g., `res.json({ status: 'ok' })`).\n- **Speed up startup:** Move heavy initialization (database seeding, large file reads) out of the main server bootstrap so the health check can succeed quickly.\n\n---\n\n### Custom domain not resolving\n\n**Symptom:** Visiting `app.yourdomain.com` shows a DNS error or \"Site not found.\"\n\n**Diagnosis:**\n\n<Steps>\n<Step title=\"Verify DNS records\">\nRun `dig yourdomain.com` or use an online DNS checker. For the root domain, you must have **two A records pointing to 162.159.142.117 and 172.66.2.113**. For `www`, add a CNAME pointing to your production hostname. Do not use a CNAME for the root domain, and never point records to a preview URL.\n</Step>\n\n<Step title=\"Wait for propagation\">\nDNS changes can take 1-48 hours to propagate globally. Test from multiple locations or use `8.8.8.8` as your resolver.\n</Step>\n\n<Step title=\"Check SSL certificate status\">\nIn the workspace, navigate to **Preview → Manage → Domain** → Check Status** and confirm the SSL certificate shows **Active-Verified**. If it shows **Pending**, wait a few more minutes; if **Failed**, double‑check your DNS records.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nDetailed setup instructions: [Custom domain](/custom-domain).\n</Callout>\n\n---\n\n## Out of credits / quota exceeded\n\n**Symptom:** Published app is rejected with `INSUFFICIENT_CREDITS`, or aborts with *\"Insufficient credits.\"* Note that live apps can still re-publish at a low balance; new published versions require a minimum credit threshold.\n\n**Cause:** Your account has consumed its [credit allocation](/managing-credit-usage) for builds, compute time, or API calls.\n\n**Fix:**\n\n- **Check your balance:** Open the **Billing** or **Usage** dashboard (depending on your plan).\n- **Upgrade or top up:** Purchase additional credits or move to a higher plan tier with more monthly allowance.\n- **Optimize usage:** Reduce the number of published versions by batching changes; use preview builds sparingly.\n\n---\n\n## Image / video / audio generation failures\n\n**Symptom:** AI‑generated media assets fail to appear or return errors.\n\n**Cause:** Model unavailable, quota exceeded, or unsupported parameters.\n\n**Fix:** See the dedicated page [AI media generation](/ai-media-generation-image-video-audio) for model‑specific troubleshooting and parameter guidance.\n\n---\n\n## Getting further help\n\nIf none of the above resolves your issue:\n\n<CardGroup cols={2}>\n<Card title=\"Ask the agent\" icon=\"message-circle\">\nPaste the full error message into chat. The agent can read logs and often auto‑fix configuration mistakes.\n</Card>\n\n<Card title=\"Review the pipeline log\" icon=\"list\" href=\"/published app-pipeline-failures\">\nStep‑by‑step guide to interpreting build and publish logs.\n</Card>\n\n<Card title=\"Check platform status\" icon=\"activity\">\nRare outages or maintenance windows are announced on the Emergent status page (link in your workspace footer).\n</Card>\n\n<Card title=\"Contact support\" icon=\"life-buoy\">\nUse the **Help** button in the workspace to open a ticket. Include your project ID and the timestamp of the failed published app.\n</Card>\n</CardGroup>\n\n<Callout type=\"success\" title=\"Most issues resolve in chat\">\nThe agent has access to your publish logs and can iterate on fixes in real time - start there before opening a support ticket.\n</Callout>","published_title":"Publishing issues","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"73d14bab-7aa2-4a40-97af-dfd7c3ce7ce4","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Publishing pipeline failures","slug":"deployment-pipeline-failures","content":"## Overview\n\nPublishing failures in Emergent typically fall into one of six categories: build-time errors, database migration timeouts, environment-secret issues, container crashes, webhook conflicts, and failed health checks. This page walks through each failure mode, its symptoms, and how to resolve it.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n<Callout type=\"tip\" title=\"Publish logs are your friend\">\nThe published app panel shows real-time logs for each stage - build, migrate, publish. When a published app fails, scroll to the error message and look for the stack trace or last successful step.\n</Callout>\n\n---\n\n## Build errors\n\nBuild failures occur during the TypeScript compile, linting, or dependency-resolution phase. Emergent runs `npm install` (or the equivalent for your package manager) then compiles your code; any error here halts the pipeline before containers are started.\n\n### Common causes\n\n- **TypeScript errors** - Type mismatches, missing imports, or incorrect generics introduced by a recent code generation.\n- **ESLint violations** - The build enforces your project's linting rules; a new unused variable or disallowed pattern will block published app.\n- **Dependency conflicts** - Incompatible package versions, missing peer dependencies, or a corrupted `package-lock.json`.\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Read the build log\">\nOpen the published app panel and expand the **Build** stage. The last few lines will show the exact file and line number.\n</Step>\n\n<Step title=\"Fix locally first\">\nReproduce the error in your local workspace (`npm run build` or `npm run lint`). Fix the issue, commit, and push.\n</Step>\n\n<Step title=\"Dependency conflicts\">\nIf the error mentions peer-dependency warnings or version mismatches, run `npm install` locally to regenerate lock files, then commit the updated `package-lock.json`.\n</Step>\n\n<Step title=\"Retry the published app\">\nOnce you've pushed the fix, trigger a new publish from the workspace or let the automatic published app pick up the latest commit.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Auto-generated code\">\nIf the agents introduced the error during a recent generation, describe the issue in chat (e.g. *\"Build is failing with TS error on line 42 of `api/users.ts`\"*) and the agent will propose a corrective change.\n</Callout>\n\n---\n\n## Database migration timeouts\n\nWhen your app includes schema changes (new collections, indexes, or data transforms), Emergent runs a migration step, on the first publish and during Replace operations, this performs a data dump/restore from preview to the production Atlas instance, before starting the new containers. If the migration script takes too long or cannot connect to MongoDB, the publish will time out.\n\n### Symptoms\n\n- Publish logs show `Running migrations…` for several minutes, then fail with a timeout or connection error.\n- No new containers are started; the previous version continues to run.\n\n### Common causes\n\n| Cause | Description |\n|-------|-------------|\n| **Large data transform** | Migration script loops over millions of documents; exceeds the timeout window. |\n| **Database unreachable** | Network issue or incorrect connection string prevents the migrator from reaching MongoDB. |\n| **Lock contention** | Another process holds a write lock on the collection being migrated. |\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Check migration logs\">\nLook for connection errors or slow query warnings in the publish panel's **Migrate** stage.\n</Step>\n\n<Step title=\"Optimize the migration\">\nIf the script is slow, refactor it to batch updates or use bulk operations. Ask the agent to rewrite the migration for better performance.\n</Step>\n\n<Step title=\"Verify connection secrets\">\nEnsure `MONGO_URL` is correctly set in your environment secrets(Preview → Manage → Secrets). See [Database (MongoDB)](/database-mongodb) for connection-string format.\n</Step>\n\n<Step title=\"Increase timeout (if available)\">\nContact support if your migration legitimately requires more than the default window; the Emergent team can adjust the timeout for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nIf the migration is a one-time backfill, consider running it manually via a script in your workspace, then removing the migration step and publishing again.\n</Callout>\n\n---\n\n## Secret-export issues\n\nPublished versions can fail if required environment variables are missing, malformed, or contain invalid characters that break the container's shell environment.\n\n### Symptoms\n\n- Publish succeeds but the app immediately crashes with `Missing required env var` or similar.\n- Logs show escaped characters or truncated secret values.\n\n### Common causes\n\n- A new feature expects an API key (e.g. `STRIPE_SECRET_KEY`) that hasn't been added to the workspace secrets.\n- Secret value contains unescaped quotes, newlines, or special shell characters.\n- Copy-paste error introduced invisible characters or trailing whitespace.\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Audit required secrets\">\nCheck your code for `process.env.VARIABLE_NAME` references and ensure each is defined in the workspace's **Secrets** panel(Preview → Manage → Secrets).\n</Step>\n\n<Step title=\"Re-enter the secret\">\nNote that keys cannot be deleted from the Secrets panel(Preview → Manage → Secrets), to correct a secret, edit the value of the existing key in the UI to eliminate hidden characters. Paste the value directly from the provider (no intermediate text editor). To add a new key, ask the agent to add it to `.env`, then re-publish.\n</Step>\n\n<Step title=\"Test locally\">\nExport the secret in your local shell (`export VAR=value`) and run the app to confirm it parses correctly.\n</Step>\n\n<Step title=\"Re-publish\">\nOnce all secrets are present and valid, trigger a new published app. The containers will pick up the updated environment.\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Universal LLM Key\">\nIf your app uses AI features, remember to set [The Universal LLM Key](/the-universal-llm-key) in secrets(Preview → Manage → Secrets) - many AI generation failures stem from a missing or expired key.\n</Callout>\n\n---\n\n## CrashLoopBackOff and OOM kills\n\nAfter a successful build, containers may crash repeatedly (CrashLoopBackOff) or be killed by the orchestrator for exceeding memory limits (OOM kill). Both prevent the published app from reaching a healthy state.\n\n### CrashLoopBackOff\n\nThe container starts but exits within seconds, triggering an automatic restart loop.\n\n**Common causes:**\n\n- Uncaught exception during startup (missing secret, database connection failure).\n- Port mismatch - app listens on a port different from the one the health check expects.\n- Syntax error or runtime crash in initialization code.\n\n**Resolution:**\n\n<Steps>\n<Step title=\"Read container logs\">\nThe publish panel's **Runtime** tab shows stdout/stderr from the crashed container. Look for the stack trace or last log line before the crash.\n</Step>\n\n<Step title=\"Fix the error\">\nAddress the root cause (add missing secret, correct the listen port, fix the exception). Commit and re-publish.\n</Step>\n\n<Step title=\"Verify health-check endpoint\">\nEnsure your app exposes the health-check route (`/health` or `/api/health`) and it returns `200 OK` when the app is ready.\n</Step>\n</Steps>\n\n### OOM kills\n\nThe container is terminated because it consumed more memory than allocated.\n\n**Symptoms:**\n\n- Logs end abruptly with no stack trace.\n- Publish panel shows `OOMKilled` or `Exit code 137`.\n\n**Resolution:**\n\n<Steps>\n<Step title=\"Identify memory-hungry code\">\nProfile the app locally or add logging to track memory usage. Common culprits: large in-memory caches, file uploads held in RAM, unbounded data fetches.\n</Step>\n\n<Step title=\"Optimize or paginate\">\nRefactor to stream large responses, paginate queries, or offload processing to a background job.\n</Step>\n\n<Step title=\"Request a memory increase\">\nIf the app legitimately needs more RAM, contact support to raise the container's memory limit for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Mobile WebView apps\">\nApps converted from web to mobile via [Web to Mobile conversion](/web-mobile-conversion-canonical) may bundle larger assets; ensure image/video assets are optimized or served from CDN rather than embedded.\n</Callout>\n\n---\n\n## Telegram 409 conflicts\n\nIf your app integrates a Telegram bot, published versions may encounter a `409 Conflict` error. This happens when more than one instance of your bot is running in polling mode simultaneously, causing conflicts over who receives updates.\n\n### Cause\n\nTelegram does not allow more than one instance to poll for updates with the same bot token at a time. If you run multiple instances (e.g. staging + production) using the same token in polling mode, Telegram rejects the duplicate poller. The fix is to switch to webhook mode or ensure only a single instance is polling.\n\n### Resolution\n\n<Steps>\n<Step title=\"Switch to webhook mode\">\nConfigure your bot to use webhooks instead of polling. Register the webhook URL with the Telegram Bot API:\n\n```bash\ncurl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourapp.emergent.host/webhook\n```\n</Step>\n\n<Step title=\"Or ensure a single poller\">\nIf you prefer polling, ensure only one instance of the bot is running at a time. Stop any duplicate instances (e.g. staging environments using the same token) before publishing.\n</Step>\n\n<Step title=\"Delete any stale webhook\">\nIf switching from webhook to polling, clear any existing webhook first:\n\n```bash\ncurl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook\n```\n</Step>\n\n<Step title=\"Re-publish\">\nTrigger a new published app. The app will initialize correctly with the chosen update method.\n</Step>\n\n<Step title=\"Use separate bot tokens per environment\">\nAvoid sharing a bot token between environments. Use separate bot tokens for staging and production to prevent conflicts regardless of update method.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nIf you recently changed your [custom domain](/custom-domain), the old webhook URL may still be registered. Deleting it resolves the conflict.\n</Callout>\n\n---\n\n## Health-check failures\n\nEmergent waits for your app to respond successfully to health-check probes before marking the published app as live. If the checks time out or return non-2xx status codes, the published app is marked as failed; the previously live version continues running (no rollback event is triggered, and an auto failure-recovery agent will attempt to resolve the issue).\n\n### Symptoms\n\n- Publish progresses past build and migrate, then stalls at **Starting containers…**\n- Logs show repeated `GET /health` or `GET /api/health` requests, all failing or timing out.\n\n### Common causes\n\n| Cause | Description |\n|-------|-------------|\n| **Missing route** | No handler defined for the health-check path. |\n| **Database dependency** | Health check queries MongoDB, but DB is unreachable or slow, causing timeouts. |\n| **Incorrect listen address** | App binds to `127.0.0.1` instead of `0.0.0.0`, making it unreachable from the orchestrator. |\n| **Slow startup** | App takes longer to initialize than the probe's initial-delay setting. |\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Implement a lightweight health endpoint\">\nEnsure your app exposes a route that returns `200 OK` without heavy logic:\n\n<CodeGroup>\n```typescript Express\napp.get('/health', (req, res) => {\n res.status(200).json({ status: 'ok' });\n});\n```\n\n```typescript Fastify\nfastify.get('/health', async () => {\n return { status: 'ok' };\n});\n```\n</CodeGroup>\n\nDo **not** query the database or external APIs in the health check - keep it instant.\n</Step>\n\n<Step title=\"Bind to 0.0.0.0\">\nVerify your server listens on all interfaces:\n\n```typescript\napp.listen(PORT, '0.0.0.0', () => {\n console.log(`Server ready on port ${PORT}`);\n});\n```\n</Step>\n\n<Step title=\"Check readiness logic\">\nIf your app must wait for DB or cache to initialize, expose a separate `/ready` endpoint and ensure the health check uses `/health` (which always returns 200).\n</Step>\n\n<Step title=\"Review probe timing\">\nContact support if your app's startup genuinely requires more time than the default initial delay; the team can adjust probe settings for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"success\" title=\"Fast health checks = faster rollouts\">\nA quick, dependency-free health endpoint ensures published versions complete in seconds and the previously live version stays up if something goes wrong.\n</Callout>\n","order":91,"parent_id":null,"icon":"rocket","description":"Specific failure modes: build errors (TS/ESLint/dependency), DB migration timeouts, secret-export issues, CrashLoopBackOff/OOM kills, Telegram 409, health-check failures.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:20.653800+00:00","published_at":"2026-09-24T14:08:20.653800+00:00","published_content":"## Overview\n\nPublishing failures in Emergent typically fall into one of six categories: build-time errors, database migration timeouts, environment-secret issues, container crashes, webhook conflicts, and failed health checks. This page walks through each failure mode, its symptoms, and how to resolve it.\n\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\n<Callout type=\"tip\" title=\"Publish logs are your friend\">\nThe published app panel shows real-time logs for each stage - build, migrate, publish. When a published app fails, scroll to the error message and look for the stack trace or last successful step.\n</Callout>\n\n---\n\n## Build errors\n\nBuild failures occur during the TypeScript compile, linting, or dependency-resolution phase. Emergent runs `npm install` (or the equivalent for your package manager) then compiles your code; any error here halts the pipeline before containers are started.\n\n### Common causes\n\n- **TypeScript errors** - Type mismatches, missing imports, or incorrect generics introduced by a recent code generation.\n- **ESLint violations** - The build enforces your project's linting rules; a new unused variable or disallowed pattern will block published app.\n- **Dependency conflicts** - Incompatible package versions, missing peer dependencies, or a corrupted `package-lock.json`.\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Read the build log\">\nOpen the published app panel and expand the **Build** stage. The last few lines will show the exact file and line number.\n</Step>\n\n<Step title=\"Fix locally first\">\nReproduce the error in your local workspace (`npm run build` or `npm run lint`). Fix the issue, commit, and push.\n</Step>\n\n<Step title=\"Dependency conflicts\">\nIf the error mentions peer-dependency warnings or version mismatches, run `npm install` locally to regenerate lock files, then commit the updated `package-lock.json`.\n</Step>\n\n<Step title=\"Retry the published app\">\nOnce you've pushed the fix, trigger a new publish from the workspace or let the automatic published app pick up the latest commit.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Auto-generated code\">\nIf the agents introduced the error during a recent generation, describe the issue in chat (e.g. *\"Build is failing with TS error on line 42 of `api/users.ts`\"*) and the agent will propose a corrective change.\n</Callout>\n\n---\n\n## Database migration timeouts\n\nWhen your app includes schema changes (new collections, indexes, or data transforms), Emergent runs a migration step, on the first publish and during Replace operations, this performs a data dump/restore from preview to the production Atlas instance, before starting the new containers. If the migration script takes too long or cannot connect to MongoDB, the publish will time out.\n\n### Symptoms\n\n- Publish logs show `Running migrations…` for several minutes, then fail with a timeout or connection error.\n- No new containers are started; the previous version continues to run.\n\n### Common causes\n\n| Cause | Description |\n|-------|-------------|\n| **Large data transform** | Migration script loops over millions of documents; exceeds the timeout window. |\n| **Database unreachable** | Network issue or incorrect connection string prevents the migrator from reaching MongoDB. |\n| **Lock contention** | Another process holds a write lock on the collection being migrated. |\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Check migration logs\">\nLook for connection errors or slow query warnings in the publish panel's **Migrate** stage.\n</Step>\n\n<Step title=\"Optimize the migration\">\nIf the script is slow, refactor it to batch updates or use bulk operations. Ask the agent to rewrite the migration for better performance.\n</Step>\n\n<Step title=\"Verify connection secrets\">\nEnsure `MONGO_URL` is correctly set in your environment secrets(Preview → Manage → Secrets). See [Database (MongoDB)](/database-mongodb) for connection-string format.\n</Step>\n\n<Step title=\"Increase timeout (if available)\">\nContact support if your migration legitimately requires more than the default window; the Emergent team can adjust the timeout for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nIf the migration is a one-time backfill, consider running it manually via a script in your workspace, then removing the migration step and publishing again.\n</Callout>\n\n---\n\n## Secret-export issues\n\nPublished versions can fail if required environment variables are missing, malformed, or contain invalid characters that break the container's shell environment.\n\n### Symptoms\n\n- Publish succeeds but the app immediately crashes with `Missing required env var` or similar.\n- Logs show escaped characters or truncated secret values.\n\n### Common causes\n\n- A new feature expects an API key (e.g. `STRIPE_SECRET_KEY`) that hasn't been added to the workspace secrets.\n- Secret value contains unescaped quotes, newlines, or special shell characters.\n- Copy-paste error introduced invisible characters or trailing whitespace.\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Audit required secrets\">\nCheck your code for `process.env.VARIABLE_NAME` references and ensure each is defined in the workspace's **Secrets** panel(Preview → Manage → Secrets).\n</Step>\n\n<Step title=\"Re-enter the secret\">\nNote that keys cannot be deleted from the Secrets panel(Preview → Manage → Secrets), to correct a secret, edit the value of the existing key in the UI to eliminate hidden characters. Paste the value directly from the provider (no intermediate text editor). To add a new key, ask the agent to add it to `.env`, then re-publish.\n</Step>\n\n<Step title=\"Test locally\">\nExport the secret in your local shell (`export VAR=value`) and run the app to confirm it parses correctly.\n</Step>\n\n<Step title=\"Re-publish\">\nOnce all secrets are present and valid, trigger a new published app. The containers will pick up the updated environment.\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Universal LLM Key\">\nIf your app uses AI features, remember to set [The Universal LLM Key](/the-universal-llm-key) in secrets(Preview → Manage → Secrets) - many AI generation failures stem from a missing or expired key.\n</Callout>\n\n---\n\n## CrashLoopBackOff and OOM kills\n\nAfter a successful build, containers may crash repeatedly (CrashLoopBackOff) or be killed by the orchestrator for exceeding memory limits (OOM kill). Both prevent the published app from reaching a healthy state.\n\n### CrashLoopBackOff\n\nThe container starts but exits within seconds, triggering an automatic restart loop.\n\n**Common causes:**\n\n- Uncaught exception during startup (missing secret, database connection failure).\n- Port mismatch - app listens on a port different from the one the health check expects.\n- Syntax error or runtime crash in initialization code.\n\n**Resolution:**\n\n<Steps>\n<Step title=\"Read container logs\">\nThe publish panel's **Runtime** tab shows stdout/stderr from the crashed container. Look for the stack trace or last log line before the crash.\n</Step>\n\n<Step title=\"Fix the error\">\nAddress the root cause (add missing secret, correct the listen port, fix the exception). Commit and re-publish.\n</Step>\n\n<Step title=\"Verify health-check endpoint\">\nEnsure your app exposes the health-check route (`/health` or `/api/health`) and it returns `200 OK` when the app is ready.\n</Step>\n</Steps>\n\n### OOM kills\n\nThe container is terminated because it consumed more memory than allocated.\n\n**Symptoms:**\n\n- Logs end abruptly with no stack trace.\n- Publish panel shows `OOMKilled` or `Exit code 137`.\n\n**Resolution:**\n\n<Steps>\n<Step title=\"Identify memory-hungry code\">\nProfile the app locally or add logging to track memory usage. Common culprits: large in-memory caches, file uploads held in RAM, unbounded data fetches.\n</Step>\n\n<Step title=\"Optimize or paginate\">\nRefactor to stream large responses, paginate queries, or offload processing to a background job.\n</Step>\n\n<Step title=\"Request a memory increase\">\nIf the app legitimately needs more RAM, contact support to raise the container's memory limit for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"warning\" title=\"Mobile WebView apps\">\nApps converted from web to mobile via [Web to Mobile conversion](/web-mobile-conversion-canonical) may bundle larger assets; ensure image/video assets are optimized or served from CDN rather than embedded.\n</Callout>\n\n---\n\n## Telegram 409 conflicts\n\nIf your app integrates a Telegram bot, published versions may encounter a `409 Conflict` error. This happens when more than one instance of your bot is running in polling mode simultaneously, causing conflicts over who receives updates.\n\n### Cause\n\nTelegram does not allow more than one instance to poll for updates with the same bot token at a time. If you run multiple instances (e.g. staging + production) using the same token in polling mode, Telegram rejects the duplicate poller. The fix is to switch to webhook mode or ensure only a single instance is polling.\n\n### Resolution\n\n<Steps>\n<Step title=\"Switch to webhook mode\">\nConfigure your bot to use webhooks instead of polling. Register the webhook URL with the Telegram Bot API:\n\n```bash\ncurl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://yourapp.emergent.host/webhook\n```\n</Step>\n\n<Step title=\"Or ensure a single poller\">\nIf you prefer polling, ensure only one instance of the bot is running at a time. Stop any duplicate instances (e.g. staging environments using the same token) before publishing.\n</Step>\n\n<Step title=\"Delete any stale webhook\">\nIf switching from webhook to polling, clear any existing webhook first:\n\n```bash\ncurl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook\n```\n</Step>\n\n<Step title=\"Re-publish\">\nTrigger a new published app. The app will initialize correctly with the chosen update method.\n</Step>\n\n<Step title=\"Use separate bot tokens per environment\">\nAvoid sharing a bot token between environments. Use separate bot tokens for staging and production to prevent conflicts regardless of update method.\n</Step>\n</Steps>\n\n<Callout type=\"info\">\nIf you recently changed your [custom domain](/custom-domain), the old webhook URL may still be registered. Deleting it resolves the conflict.\n</Callout>\n\n---\n\n## Health-check failures\n\nEmergent waits for your app to respond successfully to health-check probes before marking the published app as live. If the checks time out or return non-2xx status codes, the published app is marked as failed; the previously live version continues running (no rollback event is triggered, and an auto failure-recovery agent will attempt to resolve the issue).\n\n### Symptoms\n\n- Publish progresses past build and migrate, then stalls at **Starting containers…**\n- Logs show repeated `GET /health` or `GET /api/health` requests, all failing or timing out.\n\n### Common causes\n\n| Cause | Description |\n|-------|-------------|\n| **Missing route** | No handler defined for the health-check path. |\n| **Database dependency** | Health check queries MongoDB, but DB is unreachable or slow, causing timeouts. |\n| **Incorrect listen address** | App binds to `127.0.0.1` instead of `0.0.0.0`, making it unreachable from the orchestrator. |\n| **Slow startup** | App takes longer to initialize than the probe's initial-delay setting. |\n\n### Resolution steps\n\n<Steps>\n<Step title=\"Implement a lightweight health endpoint\">\nEnsure your app exposes a route that returns `200 OK` without heavy logic:\n\n<CodeGroup>\n```typescript Express\napp.get('/health', (req, res) => {\n res.status(200).json({ status: 'ok' });\n});\n```\n\n```typescript Fastify\nfastify.get('/health', async () => {\n return { status: 'ok' };\n});\n```\n</CodeGroup>\n\nDo **not** query the database or external APIs in the health check - keep it instant.\n</Step>\n\n<Step title=\"Bind to 0.0.0.0\">\nVerify your server listens on all interfaces:\n\n```typescript\napp.listen(PORT, '0.0.0.0', () => {\n console.log(`Server ready on port ${PORT}`);\n});\n```\n</Step>\n\n<Step title=\"Check readiness logic\">\nIf your app must wait for DB or cache to initialize, expose a separate `/ready` endpoint and ensure the health check uses `/health` (which always returns 200).\n</Step>\n\n<Step title=\"Review probe timing\">\nContact support if your app's startup genuinely requires more time than the default initial delay; the team can adjust probe settings for your workspace.\n</Step>\n</Steps>\n\n<Callout type=\"success\" title=\"Fast health checks = faster rollouts\">\nA quick, dependency-free health endpoint ensures published versions complete in seconds and the previously live version stays up if something goes wrong.\n</Callout>\n","published_title":"Publishing pipeline failures","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"de5eac58-f835-44d8-ad2b-31a6bc353354","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Works in preview but breaks in production","slug":"works-in-preview-but-breaks-in-production","content":"## Why it happens\n\nAn app that runs flawlessly in preview can break the moment you publish. This is almost always caused by **environmental differences** between the two runtimes - preview and production each have their own isolated environment, filesystem, and configuration.\n\n<Info>\nPreview and production are **completely separate containers**. A change in one does not automatically propagate to the other. See [Preview vs Published](/preview-vs-deployed-separate) for details.\n</Info>\n\n---\n\n## Common culprits\n\n### Environment variables not set in production\n\nThe most frequent cause. If your code reads `process.env.STRIPE_SECRET_KEY` and that variable exists in preview but not production, the app will fail.\n\n**What to check:**\n\n- Open the **Manage → Secrets** panel in your workspace\n- Confirm every variable your app needs is present in production\n- Environment variables flow automatically on publish, but new keys( not values) must be added to `.env` by the agent and then republished, the Secrets UI(**Manage → Secrets**) can only edit values of existing keys, not add new ones\n- Re-publish after adding missing variables\n\n<Tip>\nAgents often set variables in preview during development via `.env` files. If a key was set in the preview pod but never written to `.env`, it will not be present in production. Ask the agent to add any missing keys to `.env`, then re-publish.\n</Tip>\n\n---\n\n### Hardcoded `localhost` or preview URLs\n\nCode that references `http://localhost:3000` or your preview URL (`{slug}.preview.emergentagent.com`) will break in production because those addresses are unreachable from the live published app.\n\n**Examples:**\n\n- API base URLs: `const API = \"http://localhost:8000\"`\n- Webhook callbacks: `callbackUrl: \"https://my-app.preview.emergentagent.com/hook\"`\n- OAuth redirect URIs hardcoded to preview\n\n**Fix:**\n\nUse environment variables for all URLs:\n\n```javascript\nconst API_BASE = process.env.NEXT_PUBLIC_API_URL || \"http://localhost:3000\";\n```\n\nSet `NEXT_PUBLIC_API_URL` differently in preview vs production.\n\n---\n\n### CORS configuration pointing to the wrong origin\n\nIf your backend explicitly allows only your preview domain:\n\n```python\nallowed_origins = [\"https://my-app.preview.emergentagent.com\"]\n```\n\n…production requests from `https://my-app.emergent.host` (or your custom domain) will be blocked.\n\n**Fix:**\n\n- Use an environment variable for allowed origins\n- Or allow both domains\n- Or use a wildcard pattern if security allows\n\n---\n\n### Files written at runtime disappear\n\nProduction containers use an **ephemeral filesystem**. Any file your app writes to disk (uploads, generated PDFs, cached images) will be lost on restart or scale-out.\n\n**Symptoms:**\n\n- User uploads work initially, then vanish\n- Generated files return 404 after a few hours\n- SQLite databases lose data\n\n**Fix:**\n\nUse [Emergent Object Store](/file-storage-emergent-object-store) for persistent file storage. Never rely on the local filesystem for data that must survive restarts.\n\n<Warning title=\"Do not use local disk for persistence\">\nThe container filesystem is wiped on every re-publish and can be cleared at any time during autoscaling.\n</Warning>\n\n---\n\n### Missing system dependencies\n\nPreview may have been running on a container that happened to have a system tool installed, but production does not.\n\n**Common examples:**\n\n| Tool | Used for | Symptom in production |\n|--------------|------------------------------------|-------------------------------------------|\n| `ffmpeg` | Video encoding, audio extraction | \"ffmpeg: command not found\" |\n| Playwright | Browser automation, screenshots | Chromium binary missing |\n| ImageMagick | Image resizing, format conversion | \"convert: not found\" |\n| wkhtmltopdf | HTML-to-PDF rendering | PDF generation fails silently |\n\n**Fix:**\n\nDeclare dependencies in your project:\n\n- Add `playwright install` to your build script\n- Declare the required package dependencies explicitly in your project configuration\n- Or ask the agent to install it via system packages\n\nIf the tool was present in preview by chance, you must explicitly require it for production.\n\n---\n\n### Webhooks still pointing to preview\n\nExternal services (Stripe, Twilio, GitHub) may still have webhook URLs pointing to your preview instance.\n\n**What happens:**\n\n- Payment confirmations arrive in preview but not production\n- SMS replies are processed in the wrong environment\n- OAuth flows redirect to the old URL\n\n**Fix:**\n\n- Log into each third-party service\n- Update webhook/callback URLs to your production domain\n- Test the flow end-to-end in production\n\n<Tip title=\"Use environment-specific webhook secrets\">\nStore separate webhook signing secrets for preview and production so you can safely test webhooks without triggering real side effects.\n</Tip>\n\n---\n\n## Debugging checklist\n\n<Steps>\n<Step title=\"Compare environment variables\">\nOpen the **Preview → Manage → Secrets** panel and ensure every variable in preview also exists in production with the correct value. Remember: new keys must be added to `.env` by the agent and republished.\n</Step>\n\n<Step title=\"Check logs\">\nView production logs in the workspace. Look for missing-variable errors, connection timeouts, or \"command not found.\"\n</Step>\n\n<Step title=\"Search for hardcoded URLs\">\nGrep your codebase for `localhost`, `127.0.0.1`, `.preview.emergentagent.com` and replace with environment variables.\n</Step>\n\n<Step title=\"Verify CORS origins\">\nEnsure your backend allows requests from your production domain (or custom domain if configured).\n</Step>\n\n<Step title=\"Audit file writes\">\nIf your app writes files, confirm they go to [Object Store](/file-storage-emergent-object-store), not `/tmp` or the project directory.\n</Step>\n\n<Step title=\"Confirm system dependencies\">\nIf preview worked but production crashes on a missing binary, declare that dependency explicitly in your project configuration.\n</Step>\n\n<Step title=\"Update external webhooks\">\nCheck every third-party integration and point webhooks to your live domain.\n</Step>\n</Steps>\n\n---\n\n## Still broken?\n\n<CardGroup cols={2}>\n<Card title=\"App slow or crashing\" icon=\"gauge-high\" href=\"/app-slow-crashing-or-cold-starting\">\nPerformance and startup issues\n</Card>\n<Card title=\"Missing functionality\" icon=\"wrench\" href=\"/missing-functionality\">\nFeature worked in preview, now absent\n</Card>\n</CardGroup>\n\nIf none of the above applies, describe the exact error message in chat - agents can compare your preview and production configurations and identify the mismatch.","order":92,"parent_id":null,"icon":"eye","description":"Why an app works in preview but breaks live: separate env vars, hardcoded localhost, CORS, ephemeral filesystem losing runtime files, missing system tools (ffmpeg/Playwright), webh","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:20.651889+00:00","published_at":"2026-09-24T14:08:20.651889+00:00","published_content":"## Why it happens\n\nAn app that runs flawlessly in preview can break the moment you publish. This is almost always caused by **environmental differences** between the two runtimes - preview and production each have their own isolated environment, filesystem, and configuration.\n\n<Info>\nPreview and production are **completely separate containers**. A change in one does not automatically propagate to the other. See [Preview vs Published](/preview-vs-deployed-separate) for details.\n</Info>\n\n---\n\n## Common culprits\n\n### Environment variables not set in production\n\nThe most frequent cause. If your code reads `process.env.STRIPE_SECRET_KEY` and that variable exists in preview but not production, the app will fail.\n\n**What to check:**\n\n- Open the **Manage → Secrets** panel in your workspace\n- Confirm every variable your app needs is present in production\n- Environment variables flow automatically on publish, but new keys( not values) must be added to `.env` by the agent and then republished, the Secrets UI(**Manage → Secrets**) can only edit values of existing keys, not add new ones\n- Re-publish after adding missing variables\n\n<Tip>\nAgents often set variables in preview during development via `.env` files. If a key was set in the preview pod but never written to `.env`, it will not be present in production. Ask the agent to add any missing keys to `.env`, then re-publish.\n</Tip>\n\n---\n\n### Hardcoded `localhost` or preview URLs\n\nCode that references `http://localhost:3000` or your preview URL (`{slug}.preview.emergentagent.com`) will break in production because those addresses are unreachable from the live published app.\n\n**Examples:**\n\n- API base URLs: `const API = \"http://localhost:8000\"`\n- Webhook callbacks: `callbackUrl: \"https://my-app.preview.emergentagent.com/hook\"`\n- OAuth redirect URIs hardcoded to preview\n\n**Fix:**\n\nUse environment variables for all URLs:\n\n```javascript\nconst API_BASE = process.env.NEXT_PUBLIC_API_URL || \"http://localhost:3000\";\n```\n\nSet `NEXT_PUBLIC_API_URL` differently in preview vs production.\n\n---\n\n### CORS configuration pointing to the wrong origin\n\nIf your backend explicitly allows only your preview domain:\n\n```python\nallowed_origins = [\"https://my-app.preview.emergentagent.com\"]\n```\n\n…production requests from `https://my-app.emergent.host` (or your custom domain) will be blocked.\n\n**Fix:**\n\n- Use an environment variable for allowed origins\n- Or allow both domains\n- Or use a wildcard pattern if security allows\n\n---\n\n### Files written at runtime disappear\n\nProduction containers use an **ephemeral filesystem**. Any file your app writes to disk (uploads, generated PDFs, cached images) will be lost on restart or scale-out.\n\n**Symptoms:**\n\n- User uploads work initially, then vanish\n- Generated files return 404 after a few hours\n- SQLite databases lose data\n\n**Fix:**\n\nUse [Emergent Object Store](/file-storage-emergent-object-store) for persistent file storage. Never rely on the local filesystem for data that must survive restarts.\n\n<Warning title=\"Do not use local disk for persistence\">\nThe container filesystem is wiped on every re-publish and can be cleared at any time during autoscaling.\n</Warning>\n\n---\n\n### Missing system dependencies\n\nPreview may have been running on a container that happened to have a system tool installed, but production does not.\n\n**Common examples:**\n\n| Tool | Used for | Symptom in production |\n|--------------|------------------------------------|-------------------------------------------|\n| `ffmpeg` | Video encoding, audio extraction | \"ffmpeg: command not found\" |\n| Playwright | Browser automation, screenshots | Chromium binary missing |\n| ImageMagick | Image resizing, format conversion | \"convert: not found\" |\n| wkhtmltopdf | HTML-to-PDF rendering | PDF generation fails silently |\n\n**Fix:**\n\nDeclare dependencies in your project:\n\n- Add `playwright install` to your build script\n- Declare the required package dependencies explicitly in your project configuration\n- Or ask the agent to install it via system packages\n\nIf the tool was present in preview by chance, you must explicitly require it for production.\n\n---\n\n### Webhooks still pointing to preview\n\nExternal services (Stripe, Twilio, GitHub) may still have webhook URLs pointing to your preview instance.\n\n**What happens:**\n\n- Payment confirmations arrive in preview but not production\n- SMS replies are processed in the wrong environment\n- OAuth flows redirect to the old URL\n\n**Fix:**\n\n- Log into each third-party service\n- Update webhook/callback URLs to your production domain\n- Test the flow end-to-end in production\n\n<Tip title=\"Use environment-specific webhook secrets\">\nStore separate webhook signing secrets for preview and production so you can safely test webhooks without triggering real side effects.\n</Tip>\n\n---\n\n## Debugging checklist\n\n<Steps>\n<Step title=\"Compare environment variables\">\nOpen the **Preview → Manage → Secrets** panel and ensure every variable in preview also exists in production with the correct value. Remember: new keys must be added to `.env` by the agent and republished.\n</Step>\n\n<Step title=\"Check logs\">\nView production logs in the workspace. Look for missing-variable errors, connection timeouts, or \"command not found.\"\n</Step>\n\n<Step title=\"Search for hardcoded URLs\">\nGrep your codebase for `localhost`, `127.0.0.1`, `.preview.emergentagent.com` and replace with environment variables.\n</Step>\n\n<Step title=\"Verify CORS origins\">\nEnsure your backend allows requests from your production domain (or custom domain if configured).\n</Step>\n\n<Step title=\"Audit file writes\">\nIf your app writes files, confirm they go to [Object Store](/file-storage-emergent-object-store), not `/tmp` or the project directory.\n</Step>\n\n<Step title=\"Confirm system dependencies\">\nIf preview worked but production crashes on a missing binary, declare that dependency explicitly in your project configuration.\n</Step>\n\n<Step title=\"Update external webhooks\">\nCheck every third-party integration and point webhooks to your live domain.\n</Step>\n</Steps>\n\n---\n\n## Still broken?\n\n<CardGroup cols={2}>\n<Card title=\"App slow or crashing\" icon=\"gauge-high\" href=\"/app-slow-crashing-or-cold-starting\">\nPerformance and startup issues\n</Card>\n<Card title=\"Missing functionality\" icon=\"wrench\" href=\"/missing-functionality\">\nFeature worked in preview, now absent\n</Card>\n</CardGroup>\n\nIf none of the above applies, describe the exact error message in chat - agents can compare your preview and production configurations and identify the mismatch.","published_title":"Works in preview but breaks in production","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"3a2dd75b-8538-4de0-b869-9db61b485ee8","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"App slow, crashing or cold-starting","slug":"app-slow-crashing-or-cold-starting","content":"## Why apps slow down, crash or cold-start\n\nEmergent apps run on **KEDA-powered Kubernetes clusters** with event-driven auto-scaling and scale-to-zero when idle. This architecture keeps costs low and resources efficient, but it means some performance characteristics differ from always-on hosting.\n\n### Scale-to-zero and cold starts\n\nWhen your app receives **no requests for several minutes, KEDA scales it down to zero running pods. The next request will experience a cold start** - typically 5-15 seconds - while Kubernetes provisions a new pod, pulls the container image and boots your application.\n\nCold starts are normal and expected for low-traffic apps. High-traffic apps remain warm because continuous requests keep at least one pod running.\n\n<Tip title=\"Keep critical apps warm\">\nIf cold starts impact user experience, consider upgrading to a tier with a higher minimum replica count or configuring a health-check ping from an external monitor (e.g. UptimeRobot) every 2-3 minutes.\n</Tip>\n\n### Pod Disruption Budgets by tier\n\nEmergent applies **Pod Disruption Budgets (PDBs)** to ensure availability during cluster maintenance, upgrades and node rotations. The guarantees vary by publishing tier:\n\n| Tier | Minimum available pods | Impact |\n|------------|------------------------|-----------------------------------------|\n| Starter | None | No PDB guarantee |\n| Launch and above | 1+ | Zero-downtime rolling updates |\n\n<Warning>\nApps on lower tiers may experience **brief downtime** during platform updates. For production workloads, use Launch tier or higher.\n</Warning>\n\n### Auto-scaling behaviour (KEDA)\n\nKEDA monitors **HTTP request rate, CPU and memory** metrics. When demand increases, KEDA automatically provisions additional pods. When demand drops, pods scale back down.\n\n**Scaling thresholds:**\n- Scale up when **average CPU >70%** or **request queue depth >10**\n- Scale down after **5 minutes** of low load\n- Scale to zero after **no requests for 10 minutes** (configurable per tier)\n\n<Info>\nAuto-scaling reacts to *sustained* load, not instant spikes. A sudden traffic burst may briefly slow response times until new pods become ready (typically 10-20 seconds).\n</Info>\n\n## Common causes of slow performance\n\n### Memory or CPU limits exceeded\n\nEach tier allocates specific resource limits per pod. If your app exceeds these, Kubernetes **throttles CPU** or **kills the pod** (OOMKilled) and restarts it.\n\nCheck your app's resource usage:\n1. Open the **Workspace** and navigate to your app\n2. Click **Re-publish** to open the Managing Publishing panel\n3. Click **View Logs** in the **Overview** tab\n4. Out of memory kills show up as restarts here\n\nIf you consistently hit limits, either optimise your code (see below) or upgrade to a tier with higher per-pod resources.\n\n<Steps>\n<Step title=\"Profile your application\">\nUse `console.time()` (Node.js), `cProfile` (Python) or framework-specific profilers to find slow functions or database queries.\n</Step>\n<Step title=\"Optimise or upgrade\">\nRefactor expensive operations, add caching or move to a higher tier if the workload is legitimate.\n</Step>\n</Steps>\n\n### Slow database queries\n\nMongoDB is shared infrastructure; poorly optimised queries can slow your app and impact other users.\n\n**Common culprits:**\n- **Missing indexes** on frequently queried fields\n- **Large result sets** fetched without pagination (`limit` / `skip`)\n- **Unbounded regex queries** or full collection scans\n\n<Tip>\nUse MongoDB's `.explain()` method to inspect query plans. Add indexes for fields used in `find()`, `sort()` and aggregation pipelines. See [Database (MongoDB)](/database-mongodb) for indexing guidance.\n</Tip>\n\n### Blocking I/O or unoptimised dependencies\n\nHeavy synchronous operations - file I/O, image processing, PDF generation - block the event loop in Node.js or the main thread in Python, stalling all other requests.\n\n**Solutions:**\n- Move heavy tasks to background workers or queues\n- Use streaming APIs for large file uploads/downloads\n- Lazy-load large dependencies only when needed\n- Replace heavy libraries with lighter alternatives (e.g. `dayjs` instead of `moment`)\n\n### Cold dependency fetches\n\nIf your app fetches external resources (fonts, CSS frameworks, third-party APIs) on every request, network latency compounds. Cache responses or bundle assets at build time.\n\n## Common causes of crashes\n\n### Unhandled promise rejections / exceptions\n\nEmergent's runtime restarts crashed pods automatically, but repeated crashes trigger **CrashLoopBackOff** - the pod won't restart until you fix the code.\n\n<CodeGroup>\n```javascript Node.js\nprocess.on('unhandledRejection', (reason, promise) => {\n console.error('Unhandled Rejection:', reason);\n // Log to monitoring, do NOT exit the process\n});\n```\n\n```python Python (Flask)\n@app.errorhandler(Exception)\ndef handle_exception(e):\n app.logger.error(f\"Unhandled exception: {e}\")\n return {\"error\": \"Internal server error\"}, 500\n```\n</CodeGroup>\n\n<Warning title=\"CrashLoopBackOff\">\nIf logs (**Re-publish** -> **Overview** -> **View logs**) show repeated crashes within seconds of startup, you have a **boot-time error** (missing env var, broken import, failed DB connection). Fix the root cause - the pod won't stabilise until the error is resolved.\n</Warning>\n\n### Out-of-memory kills (OOMKilled)\n\nWhen a pod exceeds its memory limit, Kubernetes terminates it immediately. You'll see `OOMKilled` in the **View Logs** panel.\n\n**Common causes:**\n- In-memory caching of large datasets (use Redis or MongoDB instead)\n- Memory leaks (closures holding references, event listeners not cleaned up)\n- Large request payloads without streaming\n\n**Mitigation:**\n1. Add memory profiling (Node.js: `--inspect`, Python: `memory_profiler`)\n2. Implement response streaming for large data exports\n3. Use external storage (MongoDB, S3-compatible object storage) instead of in-memory buffers\n4. Upgrade tier if legitimate high-memory workload\n\n### Missing or incorrect environment variables\n\nIf your app expects an API key, database URL or config value that isn't set, it may crash on boot or on first use.\n\n<Note>\nEmergent automatically injects `MONGO_URL`, `DB_NAME`, `REACT_APP_BACKEND_URL`, and `CORS_ORIGINS`. Custom env vars must be set via the app's **Secrets** tab (**Preview → Manage → Secrets**). The [Universal LLM Key](/the-universal-llm-key) is injected only if enabled.\n</Note>\n\n## Debugging workflow\n\n<AccordionGroup>\n<Accordion title=\"How do I view real-time logs?\">\n\nOpen your app in the Workspace, Click **Re-publish** to open the Managing Publishing panel, then click **View Logs** in the **Overview** tab. Logs persist for 7 days (30 days on Pro/Enterprise).\n</Accordion>\n\n<Accordion title=\"My app works locally but crashes in production\">\nCheck for missing environment variables, file-system paths (containers are read-only except `/tmp`), or dependencies that rely on native binaries not present in the container image.\n</Accordion>\n\n<Accordion title=\"Cold starts are too slow (>20 seconds)\">\n\nLarge container images take longer to pull. Minimise dependencies, use multi-stage Docker builds (if custom Dockerfile), and ensure your app framework starts quickly (avoid heavy initialisation logic at boot).\n</Accordion>\n</AccordionGroup>\n\n## Quick performance checklist\n\n<Steps>\n<Step title=\"Add database indexes\">\nUse `.createIndex()` for fields in `find()`, `sort()` and aggregation `$match` stages.\n</Step>\n<Step title=\"Enable response caching\">\nCache expensive computations, API responses or rendered HTML for a few seconds or minutes using in-memory LRU cache or Redis.\n</Step>\n<Step title=\"Paginate large result sets\">\nNever fetch entire collections. Use `limit()` and `skip()` or cursor-based pagination.\n</Step>\n<Step title=\"Wrap async code in try/catch\">\nPrevent unhandled rejections from crashing the app. Log errors and return user-friendly messages.\n</Step>\n<Step title=\"Test under realistic load\">\nUse `autocannon` (Node.js) or `locust` (Python) to simulate concurrent users and identify bottlenecks before they hit production.\n</Step>\n</Steps>\n\n<Info title=\"Still experiencing issues?\">\nIf performance problems persist after applying these fixes, describe your symptoms in chat and agents will profile your app, suggest optimisations or recommend a tier upgrade if resource limits are the bottleneck.\n</Info>","order":93,"parent_id":null,"icon":"gauge","description":"KEDA event-driven auto-scaling, scale-to-zero cold starts, Pod Disruption Budgets by tier, and performance optimisation for slow/crashing deployed apps.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-24T14:08:20.648557+00:00","published_at":"2026-09-24T14:08:20.648557+00:00","published_content":"## Why apps slow down, crash or cold-start\n\nEmergent apps run on **KEDA-powered Kubernetes clusters** with event-driven auto-scaling and scale-to-zero when idle. This architecture keeps costs low and resources efficient, but it means some performance characteristics differ from always-on hosting.\n\n### Scale-to-zero and cold starts\n\nWhen your app receives **no requests for several minutes, KEDA scales it down to zero running pods. The next request will experience a cold start** - typically 5-15 seconds - while Kubernetes provisions a new pod, pulls the container image and boots your application.\n\nCold starts are normal and expected for low-traffic apps. High-traffic apps remain warm because continuous requests keep at least one pod running.\n\n<Tip title=\"Keep critical apps warm\">\nIf cold starts impact user experience, consider upgrading to a tier with a higher minimum replica count or configuring a health-check ping from an external monitor (e.g. UptimeRobot) every 2-3 minutes.\n</Tip>\n\n### Pod Disruption Budgets by tier\n\nEmergent applies **Pod Disruption Budgets (PDBs)** to ensure availability during cluster maintenance, upgrades and node rotations. The guarantees vary by publishing tier:\n\n| Tier | Minimum available pods | Impact |\n|------------|------------------------|-----------------------------------------|\n| Starter | None | No PDB guarantee |\n| Launch and above | 1+ | Zero-downtime rolling updates |\n\n<Warning>\nApps on lower tiers may experience **brief downtime** during platform updates. For production workloads, use Launch tier or higher.\n</Warning>\n\n### Auto-scaling behaviour (KEDA)\n\nKEDA monitors **HTTP request rate, CPU and memory** metrics. When demand increases, KEDA automatically provisions additional pods. When demand drops, pods scale back down.\n\n**Scaling thresholds:**\n- Scale up when **average CPU >70%** or **request queue depth >10**\n- Scale down after **5 minutes** of low load\n- Scale to zero after **no requests for 10 minutes** (configurable per tier)\n\n<Info>\nAuto-scaling reacts to *sustained* load, not instant spikes. A sudden traffic burst may briefly slow response times until new pods become ready (typically 10-20 seconds).\n</Info>\n\n## Common causes of slow performance\n\n### Memory or CPU limits exceeded\n\nEach tier allocates specific resource limits per pod. If your app exceeds these, Kubernetes **throttles CPU** or **kills the pod** (OOMKilled) and restarts it.\n\nCheck your app's resource usage:\n1. Open the **Workspace** and navigate to your app\n2. Click **Re-publish** to open the Managing Publishing panel\n3. Click **View Logs** in the **Overview** tab\n4. Out of memory kills show up as restarts here\n\nIf you consistently hit limits, either optimise your code (see below) or upgrade to a tier with higher per-pod resources.\n\n<Steps>\n<Step title=\"Profile your application\">\nUse `console.time()` (Node.js), `cProfile` (Python) or framework-specific profilers to find slow functions or database queries.\n</Step>\n<Step title=\"Optimise or upgrade\">\nRefactor expensive operations, add caching or move to a higher tier if the workload is legitimate.\n</Step>\n</Steps>\n\n### Slow database queries\n\nMongoDB is shared infrastructure; poorly optimised queries can slow your app and impact other users.\n\n**Common culprits:**\n- **Missing indexes** on frequently queried fields\n- **Large result sets** fetched without pagination (`limit` / `skip`)\n- **Unbounded regex queries** or full collection scans\n\n<Tip>\nUse MongoDB's `.explain()` method to inspect query plans. Add indexes for fields used in `find()`, `sort()` and aggregation pipelines. See [Database (MongoDB)](/database-mongodb) for indexing guidance.\n</Tip>\n\n### Blocking I/O or unoptimised dependencies\n\nHeavy synchronous operations - file I/O, image processing, PDF generation - block the event loop in Node.js or the main thread in Python, stalling all other requests.\n\n**Solutions:**\n- Move heavy tasks to background workers or queues\n- Use streaming APIs for large file uploads/downloads\n- Lazy-load large dependencies only when needed\n- Replace heavy libraries with lighter alternatives (e.g. `dayjs` instead of `moment`)\n\n### Cold dependency fetches\n\nIf your app fetches external resources (fonts, CSS frameworks, third-party APIs) on every request, network latency compounds. Cache responses or bundle assets at build time.\n\n## Common causes of crashes\n\n### Unhandled promise rejections / exceptions\n\nEmergent's runtime restarts crashed pods automatically, but repeated crashes trigger **CrashLoopBackOff** - the pod won't restart until you fix the code.\n\n<CodeGroup>\n```javascript Node.js\nprocess.on('unhandledRejection', (reason, promise) => {\n console.error('Unhandled Rejection:', reason);\n // Log to monitoring, do NOT exit the process\n});\n```\n\n```python Python (Flask)\n@app.errorhandler(Exception)\ndef handle_exception(e):\n app.logger.error(f\"Unhandled exception: {e}\")\n return {\"error\": \"Internal server error\"}, 500\n```\n</CodeGroup>\n\n<Warning title=\"CrashLoopBackOff\">\nIf logs (**Re-publish** -> **Overview** -> **View logs**) show repeated crashes within seconds of startup, you have a **boot-time error** (missing env var, broken import, failed DB connection). Fix the root cause - the pod won't stabilise until the error is resolved.\n</Warning>\n\n### Out-of-memory kills (OOMKilled)\n\nWhen a pod exceeds its memory limit, Kubernetes terminates it immediately. You'll see `OOMKilled` in the **View Logs** panel.\n\n**Common causes:**\n- In-memory caching of large datasets (use Redis or MongoDB instead)\n- Memory leaks (closures holding references, event listeners not cleaned up)\n- Large request payloads without streaming\n\n**Mitigation:**\n1. Add memory profiling (Node.js: `--inspect`, Python: `memory_profiler`)\n2. Implement response streaming for large data exports\n3. Use external storage (MongoDB, S3-compatible object storage) instead of in-memory buffers\n4. Upgrade tier if legitimate high-memory workload\n\n### Missing or incorrect environment variables\n\nIf your app expects an API key, database URL or config value that isn't set, it may crash on boot or on first use.\n\n<Note>\nEmergent automatically injects `MONGO_URL`, `DB_NAME`, `REACT_APP_BACKEND_URL`, and `CORS_ORIGINS`. Custom env vars must be set via the app's **Secrets** tab (**Preview → Manage → Secrets**). The [Universal LLM Key](/the-universal-llm-key) is injected only if enabled.\n</Note>\n\n## Debugging workflow\n\n<AccordionGroup>\n<Accordion title=\"How do I view real-time logs?\">\n\nOpen your app in the Workspace, Click **Re-publish** to open the Managing Publishing panel, then click **View Logs** in the **Overview** tab. Logs persist for 7 days (30 days on Pro/Enterprise).\n</Accordion>\n\n<Accordion title=\"My app works locally but crashes in production\">\nCheck for missing environment variables, file-system paths (containers are read-only except `/tmp`), or dependencies that rely on native binaries not present in the container image.\n</Accordion>\n\n<Accordion title=\"Cold starts are too slow (>20 seconds)\">\n\nLarge container images take longer to pull. Minimise dependencies, use multi-stage Docker builds (if custom Dockerfile), and ensure your app framework starts quickly (avoid heavy initialisation logic at boot).\n</Accordion>\n</AccordionGroup>\n\n## Quick performance checklist\n\n<Steps>\n<Step title=\"Add database indexes\">\nUse `.createIndex()` for fields in `find()`, `sort()` and aggregation `$match` stages.\n</Step>\n<Step title=\"Enable response caching\">\nCache expensive computations, API responses or rendered HTML for a few seconds or minutes using in-memory LRU cache or Redis.\n</Step>\n<Step title=\"Paginate large result sets\">\nNever fetch entire collections. Use `limit()` and `skip()` or cursor-based pagination.\n</Step>\n<Step title=\"Wrap async code in try/catch\">\nPrevent unhandled rejections from crashing the app. Log errors and return user-friendly messages.\n</Step>\n<Step title=\"Test under realistic load\">\nUse `autocannon` (Node.js) or `locust` (Python) to simulate concurrent users and identify bottlenecks before they hit production.\n</Step>\n</Steps>\n\n<Info title=\"Still experiencing issues?\">\nIf performance problems persist after applying these fixes, describe your symptoms in chat and agents will profile your app, suggest optimisations or recommend a tier upgrade if resource limits are the bottleneck.\n</Info>","published_title":"App slow, crashing or cold-starting","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"27bbd020-1bad-448b-9675-94385e289530","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Glossary of Emergent terms","slug":"glossary-of-emergent-terms","content":"## Agentic development\n\n**Agentic development** describes a workflow where autonomous AI agents write, test, debug and publish code on behalf of the user. In Emergent, you describe what you want in natural language and agents handle the implementation, selecting frameworks, scaffolding components, wiring APIs and iterating on feedback.\n\n---\n\n## Credits (ECU)\n\nA **credit** (internally called an ECU) is Emergent's billing unit. Building, testing and publishing apps consumes credits. Different operations cost different amounts: a simple front-end change may use a few credits, while generating video or refactoring a large codebase costs more. Credits are valued at **1 USD = 5 credits**. Your plan includes a credit allowance that refills each billing cycle; subscription credits do not roll over, but purchased top-up credits never expire.\n\n**There is no overage billing.** When your credit balance reaches zero, the current job pauses automatically and resumes once you top up.\n\nMost users on the Free plan build several full-stack projects per month before hitting their credit limit.\n\n---\n\n## Deploy / Deployment / Redeploy\n\n**Deploy / Deployment / Redeploy**: Earlier Emergent names for what is now called **Publish**, **published app**, and **Re-publish**. The platform renamed these terms; the process is unchanged. If an older guide, video, or support reply says \"deploy your app\", that means clicking **Publish**. See [Publishing types](/deployment-types).\n\n---\n\n## Job\n\nA **Job** is an app or task in Emergent, each with its own conversation, code workspace and published app. When you start a new project or task, you create a new Job. Jobs are not sub-tasks or per-request work items; each one is a self-contained unit you work on over time, with its own chat history and codebase.\n\n---\n\n## Re-publish vs Replace\n\n- **Re-publish** pushes your latest code to the live production URL. The app's environment variables, custom domain, database and settings remain unchanged. Use this for routine updates. Re-publishes are free of charge (beyond the monthly tier fee). \n- **Replace** performs a zero-downtime blue-green swap of a different job onto a live app. User secrets are carried over; you choose whether to keep the existing database or start fresh. Custom domains and subdomains persist through a Replace. Use it when you want to swap an entirely different codebase onto an existing live app.\n\n<Warning title=\"Replace swaps the underlying job\">\nReplace is intended for putting a different job onto a live publish slot, not for routine updates to the same app. Use Re-publish for standard code changes.\n</Warning>\n\n---\n\n## Universal LLM Key\n\nThe **Universal LLM Key** is a single API credential (prefixed `sk-emergent-`) that routes requests to **44+ models across 7 providers** through a unified interface. Emergent apps can call any supported model without managing multiple API keys. The Universal Key is billed at platform per-token rates with no markup; your balance is funded from your Emergent credits.\n\nCurrent model families include Claude Fable 5.x / Opus 5 / Sonnet 5 / 4.6 / Haiku 4.5; GPT-6 / GPT-5.x; and Gemini 2.5-3.8.\n\nLearn more in [The Universal LLM Key](/the-universal-llm-key).\n\n---\n\n## Maxx mode\n\n**Maxx mode** is a **Pro-only** feature that gives agents extended autonomy: deeper reasoning, permission to refactor multiple files in parallel and the ability to iterate without waiting for your approval at each step. Maxx mode consumes significantly more credits but produces higher-quality results for complex requests. Enable it by toggling the \"Maxx\" switch in the chat composer when you want the agent to \"go deep\" on a feature.\n\n<Tip>\nUse Maxx mode for new features with unclear requirements or when you want the agent to explore multiple design options.\n</Tip>\n\n---\n\n## Preview vs Published\n\n- **Preview** is the live URL that updates every time the agent saves changes. Use it to test work-in-progress features. The Preview URL is publicly accessible and sleeps after 30 minutes of inactivity. Preview and production environment variables are separate after the first publish.\n- **Published (also called \"Production\")** is the stable, published version of your app. It only updates when you explicitly click **Publish** (first time) or **Re-publish**. This is the URL you share with real users and link to custom domains, served at `<appname>.emergent.host`.\n\nPreview URLs are not indexed by search engines.\n\nRead the full comparison in [Preview vs Published](/preview-vs-deployed-separate).\n\n---\n\n## Bundle Identifier (Bundle ID)\n\nA **Bundle Identifier** is a unique reverse-domain string (for example `com.yourcompany.appname`) that identifies your mobile app on iOS and Android. Emergent seeds this into `app.json` at setup using the format `com.emergent.<words>.<suffix>`. You can edit it in the pre-populated first-build form. The Bundle ID must match across builds, code-signing certificates and app-store listings; changing it later requires new builds and re-submission to app stores.\n\n<Note>\nThe app name locks after the first build. Display name is changeable at any time. Register your package name in your own Play Console.\n</Note>\n\n---\n\n## Custom domain\n\nA **custom domain** lets you serve your published app from your own URL (for example `app.yourcompany.com` or `yourcompany.com`). Emergent provides automatic HTTPS via **Cloudflare Custom Hostnames** (not Let's Encrypt). The recommended setup method is **Auto-Link (Entri)**; for manual DNS, add **two A records pointing to 162.159.142.117 and 172.66.2.113** (plus a `www` CNAME). If your DNS is on Cloudflare, keep records set to **DNS-only (gray cloud) permanently** to avoid Error 1014.\n\nSee the step-by-step guide in [Custom domain](/custom-domain).\n\n---\n\n## MCP (Model Context Protocol)\n\n**MCP** is an open standard for exposing data sources and tools to LLMs. Emergent supports MCP servers so your agents can query databases, SaaS APIs and internal systems. You configure them in **Account Settings → Manage Agents → MCP tab** using a JSON `mcpServers` config. MCP tool lists are cached for **5 minutes**. Public MCPs are admin-created only.\n\nLearn how to add them in [Custom & MCP integrations](/custom-mcp-integrations).\n\n---\n\n## Expo & EAS (Expo Application Services)\n\n**Deploy / Deployment / Redeploy**: Other platforms' terms for what Emergent calls **Publish**, **published app**, and **Re-publish**. If a guide elsewhere says \"deploy your app\", on Emergent that means clicking **Publish**. See [Publishing types](/deployment-types).\n\n**Expo is the React Native framework Emergent uses for all mobile apps. EAS** (Expo Application Services) is Expo's cloud build and submission platform. When you generate iOS or Android builds, Emergent triggers EAS Build behind the scenes. **Emergent fully manages the Expo/EAS account**, you do not need to create an Expo account, install eas-cli, purchase EAS credits or edit `eas.json`. Native builds (APK/AAB/IPA) require a paid Emergent plan and are triggered from the Publish panel, built from your last published code.\n\n<Info>\nEmergent handles all EAS configuration automatically. Do not modify `eas.json`, changes there can break the managed build pipeline.\n</Info>\n\n---\n\n## Keystore (Android) & Certificates (iOS)\n\n- **Keystore** (Android): Cryptographic signing credentials required for publishing to Google Play. Emergent manages signing automatically. If you have a pre-existing Play Store app, Emergent provides a public `.pem`; you then request an upload-key reset in Play Console (takes 1-2 business days). Own-keystore cases go through support.\n- **Certificates & Provisioning Profiles** (iOS): Apple-issued credentials managed by Emergent through EAS. TestFlight upload is handled for you; the App Store Connect API key is auto-created and Emergent-managed. If you supply a `.p8` file, it is your **APNs push key**, uploaded at build time, missing push credentials will fail the build.\n\n<Warning>\nStore any credentials you manage securely. Losing signing keys means you cannot update your app on the respective store.\n</Warning>\n\n---\n\n## Web → Mobile conversion\n\n**Web → Mobile conversion** is Emergent's ability to transform a web app into an Expo/React Native mobile app. The feature is available via the Publish panel's \"Add Mobile App\" option (feature-flagged; excludes Next.js projects). It forks the project into a mono setup where both platforms **share the same backend**, managed in one project. Conversion is **one-way**, mobile to web requires a rebuild. Not all features convert automatically; native device APIs, camera access and push notifications may require additional work.\n\nRead the detailed guide in [Web to Mobile conversion](/web-mobile-conversion-canonical).\n\n---\n\n## Database (MongoDB)\n\nEvery Emergent project includes an optional **MongoDB cluster**. Agents can create collections, define schemas and wire CRUD operations on your behalf. The database runs on managed infrastructure; connection strings and credentials are auto-injected as the `MONGO_URL` and `DB_NAME` environment variables. You can inspect and edit data in the workspace **Database Manager** (edits are live and cannot be undone).\n\n**Important:** the managed MongoDB cluster only accepts Emergent-internal connections. You cannot connect an external Mongo client using the provided URI. For browsing data, use the built-in Database Manager at `mongoview.emergent.host` (accessible only from inside Emergent). For data exports, use `mongodump` from an allowlisted machine after migration, or migrate to your own Atlas instance.\n\nSee [Database (MongoDB)](/database-mongodb) for schema design and querying tips.\n\n---\n\n## Object storage\n\nEmergent's built-in **Object Store** supports upload, download and list operations. **Deletion of uploaded assets is not currently supported, uploads are permanent.** The storage quota is **5 GB**; exceeding it returns error **439** (`storage_quota_exceeded`). For large or permanent file storage where deletion is required, use your own AWS S3 or GCS bucket via your own keys.\n\n---\n\n## AI media generation\n\nEmergent can integrate image and video generation models through it's integrations catalogue. **Imagen 4** bills at **5×** the base credit rate; **GPT Image 1** bills at the standard rate; **Sora 2** videos are available in **4, 8 or 12-second** lengths (default 4 seconds). Free tier users cannot access the heavy media models.\n\nExplore available models in [AI media generation](/ai-media-generation-image-video-audio).\n\n---\n\n## Custom agents\n\n**Custom agents** are specialized assistants you configure for domain-specific tasks, for example a \"Marketing Copy Agent\" with tone guidelines and brand vocabulary, or a \"Data Analyst Agent\" with SQL templates. Custom agents are a **Pro plan feature**. They are configured via a 4-step wizard (system prompt, tools, sub-agents) in Account Settings → Manage Agents.\n\nLearn how to create them in [Custom agents](/custom-agents).\n\n---\n\n## Key integrations catalogue\n\nThe **Key integrations catalogue** lists pre-configured connectors (Stripe, Twilio, Resend, Shopify, ElevenLabs, etc.) that agents can install and wire. Integrations are managed from **Preview → Manage → Integrations** or by asking the agent directly; keys are stored in `.env` via the agent. Browse the full list in [Key integrations catalogue](/key-integrations-catalogue).\n\n---\n\n## Environment variables\n\n**Environment variables** store secrets (API keys, database URIs, OAuth client IDs) outside your code. Emergent auto-provisions variables for internal services (for example `MONGO_URL`, `DB_NAME`, `REACT_APP_BACKEND_URL`, `CORS_ORIGINS` and `EMERGENT_LLM_KEY`). The Secrets UI (**Preview → Manage → Secrets**) can **edit values of existing keys only**, it cannot add or delete keys. To add new keys, ask the agent to add them to `.env`, then re-publish.\n\n<Tip>\nNever paste real secrets into the chat. Chat content goes to the AI provider. Ask the agent to read keys from environment variables and enter real values under **Preview → Manage → Secrets → Custom keys**.\n</Tip>\n\n---\n\n## Workspace\n\nThe **workspace** is the web interface at **app.emergent.sh** where you review code, manage published versions, inspect logs and configure settings. It includes a file tree, live preview iframe, terminal, database browser and published app controls. Tour the interface in [A tour of the workspace](/a-tour-of-the-workspace).","order":94,"parent_id":null,"icon":"book-open","description":"Plain-language definitions users can return to: ECU, Job, Redeploy vs Replace, Universal Key, Maxx mode, Preview vs Deployed, Bundle ID, Custom domain, MCP, Expo/EAS, keystore, and","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:32.306573+00:00","published_at":"2026-09-22T06:19:32.306573+00:00","published_content":"## Agentic development\n\n**Agentic development** describes a workflow where autonomous AI agents write, test, debug and publish code on behalf of the user. In Emergent, you describe what you want in natural language and agents handle the implementation, selecting frameworks, scaffolding components, wiring APIs and iterating on feedback.\n\n---\n\n## Credits (ECU)\n\nA **credit** (internally called an ECU) is Emergent's billing unit. Building, testing and publishing apps consumes credits. Different operations cost different amounts: a simple front-end change may use a few credits, while generating video or refactoring a large codebase costs more. Credits are valued at **1 USD = 5 credits**. Your plan includes a credit allowance that refills each billing cycle; subscription credits do not roll over, but purchased top-up credits never expire.\n\n**There is no overage billing.** When your credit balance reaches zero, the current job pauses automatically and resumes once you top up.\n\nMost users on the Free plan build several full-stack projects per month before hitting their credit limit.\n\n---\n\n## Deploy / Deployment / Redeploy\n\n**Deploy / Deployment / Redeploy**: Earlier Emergent names for what is now called **Publish**, **published app**, and **Re-publish**. The platform renamed these terms; the process is unchanged. If an older guide, video, or support reply says \"deploy your app\", that means clicking **Publish**. See [Publishing types](/deployment-types).\n\n---\n\n## Job\n\nA **Job** is an app or task in Emergent, each with its own conversation, code workspace and published app. When you start a new project or task, you create a new Job. Jobs are not sub-tasks or per-request work items; each one is a self-contained unit you work on over time, with its own chat history and codebase.\n\n---\n\n## Re-publish vs Replace\n\n- **Re-publish** pushes your latest code to the live production URL. The app's environment variables, custom domain, database and settings remain unchanged. Use this for routine updates. Re-publishes are free of charge (beyond the monthly tier fee). \n- **Replace** performs a zero-downtime blue-green swap of a different job onto a live app. User secrets are carried over; you choose whether to keep the existing database or start fresh. Custom domains and subdomains persist through a Replace. Use it when you want to swap an entirely different codebase onto an existing live app.\n\n<Warning title=\"Replace swaps the underlying job\">\nReplace is intended for putting a different job onto a live publish slot, not for routine updates to the same app. Use Re-publish for standard code changes.\n</Warning>\n\n---\n\n## Universal LLM Key\n\nThe **Universal LLM Key** is a single API credential (prefixed `sk-emergent-`) that routes requests to **44+ models across 7 providers** through a unified interface. Emergent apps can call any supported model without managing multiple API keys. The Universal Key is billed at platform per-token rates with no markup; your balance is funded from your Emergent credits.\n\nCurrent model families include Claude Fable 5.x / Opus 5 / Sonnet 5 / 4.6 / Haiku 4.5; GPT-6 / GPT-5.x; and Gemini 2.5-3.8.\n\nLearn more in [The Universal LLM Key](/the-universal-llm-key).\n\n---\n\n## Maxx mode\n\n**Maxx mode** is a **Pro-only** feature that gives agents extended autonomy: deeper reasoning, permission to refactor multiple files in parallel and the ability to iterate without waiting for your approval at each step. Maxx mode consumes significantly more credits but produces higher-quality results for complex requests. Enable it by toggling the \"Maxx\" switch in the chat composer when you want the agent to \"go deep\" on a feature.\n\n<Tip>\nUse Maxx mode for new features with unclear requirements or when you want the agent to explore multiple design options.\n</Tip>\n\n---\n\n## Preview vs Published\n\n- **Preview** is the live URL that updates every time the agent saves changes. Use it to test work-in-progress features. The Preview URL is publicly accessible and sleeps after 30 minutes of inactivity. Preview and production environment variables are separate after the first publish.\n- **Published (also called \"Production\")** is the stable, published version of your app. It only updates when you explicitly click **Publish** (first time) or **Re-publish**. This is the URL you share with real users and link to custom domains, served at `<appname>.emergent.host`.\n\nPreview URLs are not indexed by search engines.\n\nRead the full comparison in [Preview vs Published](/preview-vs-deployed-separate).\n\n---\n\n## Bundle Identifier (Bundle ID)\n\nA **Bundle Identifier** is a unique reverse-domain string (for example `com.yourcompany.appname`) that identifies your mobile app on iOS and Android. Emergent seeds this into `app.json` at setup using the format `com.emergent.<words>.<suffix>`. You can edit it in the pre-populated first-build form. The Bundle ID must match across builds, code-signing certificates and app-store listings; changing it later requires new builds and re-submission to app stores.\n\n<Note>\nThe app name locks after the first build. Display name is changeable at any time. Register your package name in your own Play Console.\n</Note>\n\n---\n\n## Custom domain\n\nA **custom domain** lets you serve your published app from your own URL (for example `app.yourcompany.com` or `yourcompany.com`). Emergent provides automatic HTTPS via **Cloudflare Custom Hostnames** (not Let's Encrypt). The recommended setup method is **Auto-Link (Entri)**; for manual DNS, add **two A records pointing to 162.159.142.117 and 172.66.2.113** (plus a `www` CNAME). If your DNS is on Cloudflare, keep records set to **DNS-only (gray cloud) permanently** to avoid Error 1014.\n\nSee the step-by-step guide in [Custom domain](/custom-domain).\n\n---\n\n## MCP (Model Context Protocol)\n\n**MCP** is an open standard for exposing data sources and tools to LLMs. Emergent supports MCP servers so your agents can query databases, SaaS APIs and internal systems. You configure them in **Account Settings → Manage Agents → MCP tab** using a JSON `mcpServers` config. MCP tool lists are cached for **5 minutes**. Public MCPs are admin-created only.\n\nLearn how to add them in [Custom & MCP integrations](/custom-mcp-integrations).\n\n---\n\n## Expo & EAS (Expo Application Services)\n\n**Deploy / Deployment / Redeploy**: Other platforms' terms for what Emergent calls **Publish**, **published app**, and **Re-publish**. If a guide elsewhere says \"deploy your app\", on Emergent that means clicking **Publish**. See [Publishing types](/deployment-types).\n\n**Expo is the React Native framework Emergent uses for all mobile apps. EAS** (Expo Application Services) is Expo's cloud build and submission platform. When you generate iOS or Android builds, Emergent triggers EAS Build behind the scenes. **Emergent fully manages the Expo/EAS account**, you do not need to create an Expo account, install eas-cli, purchase EAS credits or edit `eas.json`. Native builds (APK/AAB/IPA) require a paid Emergent plan and are triggered from the Publish panel, built from your last published code.\n\n<Info>\nEmergent handles all EAS configuration automatically. Do not modify `eas.json`, changes there can break the managed build pipeline.\n</Info>\n\n---\n\n## Keystore (Android) & Certificates (iOS)\n\n- **Keystore** (Android): Cryptographic signing credentials required for publishing to Google Play. Emergent manages signing automatically. If you have a pre-existing Play Store app, Emergent provides a public `.pem`; you then request an upload-key reset in Play Console (takes 1-2 business days). Own-keystore cases go through support.\n- **Certificates & Provisioning Profiles** (iOS): Apple-issued credentials managed by Emergent through EAS. TestFlight upload is handled for you; the App Store Connect API key is auto-created and Emergent-managed. If you supply a `.p8` file, it is your **APNs push key**, uploaded at build time, missing push credentials will fail the build.\n\n<Warning>\nStore any credentials you manage securely. Losing signing keys means you cannot update your app on the respective store.\n</Warning>\n\n---\n\n## Web → Mobile conversion\n\n**Web → Mobile conversion** is Emergent's ability to transform a web app into an Expo/React Native mobile app. The feature is available via the Publish panel's \"Add Mobile App\" option (feature-flagged; excludes Next.js projects). It forks the project into a mono setup where both platforms **share the same backend**, managed in one project. Conversion is **one-way**, mobile to web requires a rebuild. Not all features convert automatically; native device APIs, camera access and push notifications may require additional work.\n\nRead the detailed guide in [Web to Mobile conversion](/web-mobile-conversion-canonical).\n\n---\n\n## Database (MongoDB)\n\nEvery Emergent project includes an optional **MongoDB cluster**. Agents can create collections, define schemas and wire CRUD operations on your behalf. The database runs on managed infrastructure; connection strings and credentials are auto-injected as the `MONGO_URL` and `DB_NAME` environment variables. You can inspect and edit data in the workspace **Database Manager** (edits are live and cannot be undone).\n\n**Important:** the managed MongoDB cluster only accepts Emergent-internal connections. You cannot connect an external Mongo client using the provided URI. For browsing data, use the built-in Database Manager at `mongoview.emergent.host` (accessible only from inside Emergent). For data exports, use `mongodump` from an allowlisted machine after migration, or migrate to your own Atlas instance.\n\nSee [Database (MongoDB)](/database-mongodb) for schema design and querying tips.\n\n---\n\n## Object storage\n\nEmergent's built-in **Object Store** supports upload, download and list operations. **Deletion of uploaded assets is not currently supported, uploads are permanent.** The storage quota is **5 GB**; exceeding it returns error **439** (`storage_quota_exceeded`). For large or permanent file storage where deletion is required, use your own AWS S3 or GCS bucket via your own keys.\n\n---\n\n## AI media generation\n\nEmergent can integrate image and video generation models through it's integrations catalogue. **Imagen 4** bills at **5×** the base credit rate; **GPT Image 1** bills at the standard rate; **Sora 2** videos are available in **4, 8 or 12-second** lengths (default 4 seconds). Free tier users cannot access the heavy media models.\n\nExplore available models in [AI media generation](/ai-media-generation-image-video-audio).\n\n---\n\n## Custom agents\n\n**Custom agents** are specialized assistants you configure for domain-specific tasks, for example a \"Marketing Copy Agent\" with tone guidelines and brand vocabulary, or a \"Data Analyst Agent\" with SQL templates. Custom agents are a **Pro plan feature**. They are configured via a 4-step wizard (system prompt, tools, sub-agents) in Account Settings → Manage Agents.\n\nLearn how to create them in [Custom agents](/custom-agents).\n\n---\n\n## Key integrations catalogue\n\nThe **Key integrations catalogue** lists pre-configured connectors (Stripe, Twilio, Resend, Shopify, ElevenLabs, etc.) that agents can install and wire. Integrations are managed from **Preview → Manage → Integrations** or by asking the agent directly; keys are stored in `.env` via the agent. Browse the full list in [Key integrations catalogue](/key-integrations-catalogue).\n\n---\n\n## Environment variables\n\n**Environment variables** store secrets (API keys, database URIs, OAuth client IDs) outside your code. Emergent auto-provisions variables for internal services (for example `MONGO_URL`, `DB_NAME`, `REACT_APP_BACKEND_URL`, `CORS_ORIGINS` and `EMERGENT_LLM_KEY`). The Secrets UI (**Preview → Manage → Secrets**) can **edit values of existing keys only**, it cannot add or delete keys. To add new keys, ask the agent to add them to `.env`, then re-publish.\n\n<Tip>\nNever paste real secrets into the chat. Chat content goes to the AI provider. Ask the agent to read keys from environment variables and enter real values under **Preview → Manage → Secrets → Custom keys**.\n</Tip>\n\n---\n\n## Workspace\n\nThe **workspace** is the web interface at **app.emergent.sh** where you review code, manage published versions, inspect logs and configure settings. It includes a file tree, live preview iframe, terminal, database browser and published app controls. Tour the interface in [A tour of the workspace](/a-tour-of-the-workspace).","published_title":"Glossary of Emergent terms","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"288fdffa-de94-4d40-888c-0ffc0abad2f8","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"FAQs","slug":"faqs","content":"## Frequently Asked Questions\n\n<AccordionGroup>\n\n<Accordion title=\"What is Emergent?\">\nEmergent is an agentic vibe-coding platform where you describe an app in natural language and AI agents build, test, and publish it for you. You chat with the platform, refine your vision iteratively, and Emergent handles the implementation - front-end, back-end, database, hosting, and published app.\n</Accordion>\n\n<Accordion title=\"How does the chat-to-published app flow work?\">\nYou describe your app idea in the chat interface. Emergent's AI agents interpret your requirements, generate code, provision infrastructure, and publish a working application. You can refine and iterate by continuing the conversation. For a detailed walkthrough, see [The chat-to-published app flow](/the-chat-to-deployment-flow).\n</Accordion>\n\n<Accordion title=\"Do I need to know how to code?\">\nNo. Emergent is designed for users of all technical levels. You describe what you want in plain language, and the platform handles the technical implementation. If you *do* know how to code, you can also provide detailed technical guidance or even paste code snippets to steer the agents.\n</Accordion>\n\n<Accordion title=\"What types of applications can I build?\">\nEmergent supports a wide range of applications including web apps, mobile apps (iOS and Android via React Native), dashboards, APIs, SaaS tools, MVPs, prototypes, and internal business tools. The platform handles full-stack development with database integration, authentication, payments, and more.\n</Accordion>\n\n<Accordion title=\"Can I convert a web app to mobile or vice versa?\">\nYes. Emergent can convert web applications to React Native mobile apps and vice versa. The conversion process preserves your data and core functionality while adapting the UI and navigation patterns for the target platform. See [Web to Mobile conversion](/web-mobile-conversion-canonical) for details.\n</Accordion>\n\n<Accordion title=\"What technologies does Emergent use under the hood?\">\nEmergent builds apps using modern, production-ready stacks:\n\n- **Front-end:** React, Next.js, Tailwind CSS, shadcn/ui components\n- **Mobile:** React Native with Expo\n- **Back-end:** Python/FastAPI or Next.js API routes, REST APIs, running in Docker on Emergent's Kubernetes\n- **Database:** MongoDB Atlas (managed, scalable)\n- **Hosting:** Emergent's infrastructure (emergent.host, Cloudflare) for web; Expo Application Services for mobile\n- **Authentication:** Emergent Auth, or Auth0, Clerk, and other integrations\n- **Payments:** Stripe integration\n\nThe specific stack may vary based on your app's requirements.\n</Accordion>\n\n<Accordion title=\"How is my data stored and secured?\">\nData is stored in a MongoDB Atlas database provisioned for your project (shared cluster by default; a Dedicated Database is a paid upgrade). Each app gets its own isolated database with industry-standard encryption at rest and in transit. You own your data; note that production data export is not currently self-serve, use your own external DB or `mongodump` from an allowlisted machine after migration. See [Database (MongoDB)](/database-mongodb) for more.\n</Accordion>\n\n<Accordion title=\"Can I use my own API keys or bring my own LLM?\">\nYes. Emergent provides a [Universal LLM Key](/the-universal-llm-key) for convenience, but you can bring your own API keys for OpenAI, Anthropic, Google, or other providers. You can configure per-project LLM preferences and manage keys in your workspace settings.\n</Accordion>\n\n<Accordion title=\"How do I publish my app to production?\">\nClick **Publish** to publish your app for the first time (or **Re-publish** for subsequent publishes). The pipeline takes approximately 10-15 minutes and provisions hosting, configures environment variables, and makes your app live at your `<appname>.emergent.host` URL. You can also connect a [custom domain](/custom-domain) to your published app.\n</Accordion>\n\n<Accordion title=\"Why does Emergent say Publish instead of Deploy? Where did the Deploy button go?\">\nEmergent renamed deploying to publishing. **Deploy** and **Redeploy** are now **Publish** and **Re-publish**, deployments are called publishes, and the panel is **Manage Publishing**. Only the name changed - the process, your live apps, and your URLs are exactly the same. Older tutorials that say \"deploy\" still apply; just click Publish.\n</Accordion>\n\n<Accordion title=\"Can I connect a custom domain to my app?\">\nYes. Once your app is published, you can connect your own domain name through the workspace settings. Emergent handles DNS configuration and SSL certificate provisioning. See [Custom domain](/custom-domain) for step-by-step instructions.\n</Accordion>\n\n<Accordion title=\"What happens if I want to iterate or make changes after published app?\">\nContinue the conversation in chat. Describe the changes you want, and Emergent's agents will update the code, re-run tests, and publish the new version. Your database and user data persist across iterations.\n</Accordion>\n\n<Accordion title=\"Can I export my code and self-host?\">\nOn paid plans (Standard and above), you can push your application's source code to GitHub via the **Save → Save to GitHub** feature. There is no download/archive button; code leaves the platform via GitHub push or by copying from the VS Code view (available on all plans). You can then publish it to any hosting provider you choose.\n</Accordion>\n\n<Accordion title=\"Does Emergent support authentication and user management?\">\nYes. Emergent includes **Emergent Auth** (built-in), which supports email/password, Google sign-in (no extra keys needed), and phone OTP. You can also integrate Auth0, Clerk, or Firebase Auth. Ask the agent to add authentication to your app.\n</Accordion>\n\n<Accordion title=\"Can I integrate third-party APIs and services?\">\nAbsolutely. Tell Emergent which APIs or services you want to integrate (Stripe, Twilio, SendGrid, Google Maps, etc.), and the agents will generate the integration code, handle authentication, and configure environment variables.\n</Accordion>\n\n<Accordion title=\"How do I manage environment variables and secrets?\">\nEnvironment variables and secrets are managed through the workspace settings (**Preview → Manage → Secrets**). You can edit values of existing keys there. To add new keys, ask the agent to add them to `.env`, then re-publish. Secrets are encrypted and never exposed in the codebase.\n</Accordion>\n\n<Accordion title=\"What is the workspace and how do I navigate it?\">\nThe workspace is your project hub where you can view code, logs, database records, publish history, settings, and more. It provides a visual interface for monitoring and managing your app. See [A tour of the workspace](/a-tour-of-the-workspace) for a complete overview.\n</Accordion>\n\n<Accordion title=\"Can I collaborate with a team on an Emergent project?\">\nTeam collaboration features vary by plan. You can invite collaborators to view or edit projects, manage permissions, and work together in the same workspace. Check your plan details for collaboration limits.\n</Accordion>\n\n<Accordion title=\"What are the pricing plans and limits?\">\nEmergent offers multiple pricing tiers with different quotas for projects, published versions, compute, storage, and team members. Visit the Emergent pricing page or your account dashboard for the latest plan details and limits.\n</Accordion>\n\n<Accordion title=\"How do I upgrade or downgrade my plan?\">\nYou can change your subscription tier at any time from the billing section of your account settings. Upgrades take effect immediately; downgrades apply at the end of the current billing cycle.\n</Accordion>\n\n<Accordion title=\"What happens if I hit a usage limit?\">\nIf you reach a plan limit (projects, API calls, storage, etc.), you'll receive a notification. Depending on the limit, the platform may pause certain operations until you upgrade or the next billing cycle begins. Critical functionality like accessing your code and data remains available.\n</Accordion>\n\n<Accordion title=\"Can I cancel my subscription at any time?\">\nYes. You can cancel your subscription from the billing settings. Your access continues until the end of the current billing period, after which your account transitions to the Free plan.\n</Accordion>\n\n<Accordion title=\"What support options are available?\">\nSupport options depend on your plan. All users have access to documentation, in-app live chat (Emmy, primary/fastest), Discord community, and email support at support@emergent.sh.\n\nHigher-tier plans may include priority support or forward published engineers.\n</Accordion>\n\n<Accordion title=\"How do I report a bug or request a feature?\">\n\nUse the feedback widget in the workspace, or contact support via email at support@emergent.sh. Feature requests are tracked and prioritized based on user demand. You can also join the Emergent community to vote on and discuss upcoming features.\n</Accordion>\n\n<Accordion title=\"Is there a limit to how many times I can iterate on an app?\">\nIteration limits depend on your plan. Most plans allow unlimited iterations within reasonable usage bounds. Compute-intensive operations (like full re-builds) may count toward usage quotas.\n</Accordion>\n\n<Accordion title=\"Can I build apps in languages other than English?\">\nYes. Emergent supports natural-language input in multiple languages. You can describe your app in your preferred language, and the platform will generate code and content accordingly.\n</Accordion>\n\n<Accordion title=\"Does Emergent support internationalization (i18n) in apps?\">\nYes. You can request multi-language support for your app, and Emergent will generate i18n-ready code with locale management, translation keys, and language switchers.\n</Accordion>\n\n<Accordion title=\"What testing does Emergent perform on my app?\">\nEmergent's agents run automated tests during the build process, including unit tests, integration tests, and basic end-to-end smoke tests. You can also request additional test coverage or specific testing scenarios.\n</Accordion>\n\n<Accordion title=\"Can I access the database directly?\">\nYou can query and manage your MongoDB database through the Database Manager in the workspace interface. External MongoDB client connections are not supported, the managed cluster rejects external connections. All browsing and editing must be done via the Database Manager (note: it edits live data with no undo).\n</Accordion>\n\n<Accordion title=\"How do I back up my database?\">\nThe platform manages backups automatically. There is no Atlas console access for configuring additional backup policies. You can migrate your data to your own external database using the manual runbook (export → import → allowlist Emergent's egress IPs → update `MONGO_URL`/`DB_NAME` → re-publish) if you need more control.\n</Accordion>\n\n<Accordion title=\"What happens to my data if I delete a project?\">\n<Warning>\nDeleting a project permanently removes the codebase, database, and all associated resources. This action cannot be undone. Always export your code and data before deletion.\n</Warning>\n</Accordion>\n\n<Accordion title=\"Can I import an existing codebase into Emergent?\">\nYes. You can import an existing codebase when starting a new job, connect your GitHub account (OAuth), provide a public URL, or ask the agent. Note that importing is only available at new-job creation; there is no mid-job pull or in-platform sync.\n</Accordion>\n\n<Accordion title=\"Does Emergent support mobile app store published app?\">\nYes. For React Native apps, Emergent integrates with Expo Application Services (EAS) to build and submit apps to the Apple App Store and Google Play Store. You'll need developer accounts with Apple and Google.\n</Accordion>\n\n<Accordion title=\"How do I handle app updates after publishing to app stores?\">\nContinue iterating in Emergent as usual. When you're ready to release an update, Emergent can rebuild and submit the new version through EAS. You control the release schedule and versioning.\n</Accordion>\n\n<Accordion title=\"What are the system requirements for using Emergent?\">\nEmergent is a cloud-based platform accessible via any modern web browser (Chrome, Firefox, Safari, Edge). No local installation or specific hardware is required. For mobile app testing, you can use simulators (included) or physical devices.\n</Accordion>\n\n<Accordion title=\"Can I use Emergent offline?\">\nNo. Emergent is a cloud platform that requires an internet connection for the AI agents to build, test, and publish your apps.\n</Accordion>\n\n<Accordion title=\"Where can I learn more about Emergent-specific terminology?\">\nSee the [Glossary of Emergent terms](/glossary-of-emergent-terms) for definitions of platform-specific concepts like agents, vibes, canonical builds, and more.\n</Accordion>\n\n<Accordion title=\"How does Emergent handle versioning and rollbacks?\">\n\nEmergent maintains a publish history in the workspace. You can view past versions and roll back to one of up to 3 previous images if needed. Each published app is tagged with a timestamp.\n\nEach published app is tagged with a changelog.\n</Accordion>\n\n<Accordion title=\"Can I schedule published versions or automate workflows?\">\nAdvanced automation features (like scheduled published versions or CI/CD integrations) may be available on higher-tier plans or through API access. Check your plan details or contact support for specifics.\n</Accordion>\n\n<Accordion title=\"What happens if an agent makes a mistake or breaks my app?\">\nEmergent agents are designed to test and validate changes before published app. If an issue occurs, you can roll back to a previous version, describe the problem in chat, and the agents will attempt to fix it. You can also manually edit code in the workspace.\n</Accordion>\n\n<Accordion title=\"Is my intellectual property protected?\">\nYes. You retain full ownership of the applications and content you create with Emergent. Emergent does not claim ownership of your ideas, code, or data.\n</Accordion>\n\n<Accordion title=\"Does Emergent comply with data protection regulations (GDPR, etc.)?\">\n\nEmergent follows industry best practices for data security and privacy. For specific compliance questions or data processing agreements, contact the Emergent legal or support team.\n</Accordion>\n\n<Accordion title=\"Can I white-label or resell apps built on Emergent?\">\nYes. You own the apps you build and can white-label, resell, or commercialize them as you see fit. Check your plan's terms of service for any restrictions.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n<Callout type=\"info\" title=\"Still have questions?\">\nIf your question isn't answered here, check the rest of the documentation or reach out to Emergent support. We're here to help you succeed.\n</Callout>\n\n---\n\n## Common questions by topic\n\n### Prompting\n\n<AccordionGroup>\n<Accordion title=\"Why doesn't pasting my ChatGPT plan/spec produce what I expect?\">\nAn external spec written for another tool often doesn't map to Emergent's build flow. Emergent works best when you describe features conversationally and let the agent ask clarifying questions, rather than dropping in a large pre-written plan. Break the plan into smaller feature requests and iterate.\n</Accordion>\n<Accordion title=\"How should I phrase prompts to get better results?\">\nSmall, concise feature requests beat mega-prompts, they lower credit burn and reduce confusion. Describe one capability at a time, answer the agent's clarifying questions (Universal Key vs your own key, auth, design preferences), and refine step by step.\n</Accordion>\n</AccordionGroup>\n\n### Models & agent quality\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between E1, E2, E3 and the underlying models?\">\nE1, E2 and E3 are Emergent's agent tiers (different workflows), chosen from the agent dropdown at job creation; the LLM is a separate model selector. They differ in capability and cost, higher tiers apply more reasoning to complex work. Pick the tier that matches how hard your task is.\n</Accordion>\n<Accordion title=\"What is Maxx mode and how does it affect credit consumption?\">\nMaxx mode (Pro-only) runs the agent at higher effort for tougher tasks and, as a result, consumes significantly more credits. Use it when standard runs get stuck.\n</Accordion>\n</AccordionGroup>\n\n### Credits\n\n<AccordionGroup>\n<Accordion title=\"How are credits deducted and what makes an app consume more?\">\nCredits are consumed by generation, testing, cloud publishes and integrations. App complexity and Maxx mode drive higher usage.\n</Accordion>\n<Accordion title=\"How much does a single prompt cost in credits?\">\nIt varies with the work the agent does. You can set a limit to cap consumption so a single prompt can't run away.\n</Accordion>\n<Accordion title=\"Do my credits expire? When do they reset?\">\nMonthly subscription credits do not roll over, they refill to the cap at each billing cycle. Purchased top-up credits never expire. Promotional/boost credits carry a shown expiry date. Free tier users receive 10 credits on their first day.\n</Accordion>\n<Accordion title=\"What happens if I run low on credits mid-prompt?\">\nThe build pauses when credits run out; top up to continue. A published app charge can take an already-at-or-below-zero balance negative; jobs pause at zero and there is no separate renewal takedown threshold.\n</Accordion>\n<Accordion title=\"What are the different types of credits (Universal Key vs Emergent credits)?\">\n**Emergent Credits** pay for building on the platform. The **Universal LLM Key** uses Emergent Credits to call GPT / Claude / Gemini without setting up your own API key. You can top up either at any time, just don't confuse the two.\n</Accordion>\n</AccordionGroup>\n\n### Plans\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between Standard and Pro?\">\nThe Free plan provides daily credit grants (10 on day one) but cannot publish. Standard and Pro differ in included credits and features; Pro adds more capability. See the Plans & billing pages for the current breakdown.\n</Accordion>\n<Accordion title=\"Which publishing plan do I need (how much CPU/memory)?\">\nPublishing tiers are Starter, Launch, Grow, Scale, and Elite, each a fixed monthly credit fee with increasing CPU/memory. Pick the tier that matches your app's resource needs; you can move up if it runs hot.\n</Accordion>\n</AccordionGroup>\n\n### Prompt windows\n\n<AccordionGroup>\n<Accordion title=\"Which prompt window should I use - Fullstack, Mobile, Landing page, or Brainstorm?\">\nUse **Fullstack Builder** for full web apps, **Mobile App** for native iOS/Android apps, **Landing Page** for marketing pages, and **Brainstorm** to plan an idea before building. See \"Compare the 4 windows\".\n</Accordion>\n<Accordion title=\"What are the limitations specific to each job type (mobile vs web)?\">\nA native **Mobile App** runs on a different stack underneath, it is **not** a web URL in a wrapper, which changes its domain, bundle-ID and publishing behaviour. **Web** apps publish to a URL and use re-publish/replace.\n</Accordion>\n</AccordionGroup>\n\n### Mobile\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between a native mobile app and a web URL?\">\nA native app is compiled for iOS/Android and installed from the app stores; a web app is a URL you open in a browser. Native apps have no domain attached.\n</Accordion>\n<Accordion title=\"Is there a step-by-step guide to publish to the Play Store / App Store?\">\nYes. Preview and test on-device, generate a build, then publish to the stores. See the mobile publishing guide for the per-platform steps and review timelines.\n</Accordion>\n<Accordion title=\"What are package name, bundle ID and app ID - and why can't I change them after the first build?\">\nThey identify your app to Android (package name) and iOS (bundle ID). They are generated at the first build/publish and **locked** afterwards, so plan them before your first build.\n</Accordion>\n<Accordion title=\"Why did my integration (e.g. Apple Music) break after publishing?\">\nAn integration must use the **same bundle ID** as your app. If the bundle ID configured with the provider doesn't match your app's, the integration breaks.\n</Accordion>\n</AccordionGroup>\n\n### Web ↔ Mobile\n\n<AccordionGroup>\n<Accordion title=\"Will I lose data or functionality when converting between web and mobile?\">\nConverting adapts the UI and navigation for the target platform while preserving your data and core functionality. Mobile uses the same backend database as your web app.\n</Accordion>\n</AccordionGroup>\n\n### Custom domain\n\n<AccordionGroup>\n<Accordion title=\"My custom domain is stuck / not loading - how do I fix it?\">\nMost cases are a DNS fix: add an **A record** pointing to the Emergent IP shown in the Custom Domain flow, plus a **CNAME `www`** entry with your domain value. Give DNS time to propagate. (Web apps only.)\n</Accordion>\n<Accordion title=\"Do I need a custom domain for a mobile app?\">\nNo. Native mobile apps have no domain attached, so there's nothing to buy.\n</Accordion>\n<Accordion title=\"What is the emergent subdomain (www.app...) and will it work?\">\nEvery web app gets a built-in Emergent subdomain (`<appname>.emergent.host`) that works as-is. Default subdomains cannot be renamed. A custom domain is optional, add one when you want your own branded URL.\n</Accordion>\n</AccordionGroup>\n\n### Changing your app's name\n\n<AccordionGroup>\n<Accordion title=\"Can I change the name of my app on the emergent domain?\">\nThe default Emergent subdomain (`<appname>.emergent.host`) cannot be changed. To use a different name, add a custom domain; the built-in subdomain itself is fixed.\n</Accordion>\n<Accordion title='Google auth shows \"login to xyz\" but I want it to say something else - why?'>\nThat consent-screen name comes from the OAuth app configured with Google, not from Emergent. Update the app name in your Google OAuth (Google Cloud) credentials and the screen will follow.\n</Accordion>\n</AccordionGroup>\n\n### Published app\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between re-publish and replace published app?\">\n**Re-publish** (**Re-publish**) pushes your latest code to the live app free of charge  and picks up any new environment variable keys added to `.env`. **Replace** pushes code and can also swap the production database.\n</Accordion>\n<Accordion title='Why does my database only change when I use \"replace\"?'>\nRe-publish keeps your existing production database untouched. The production database only changes when you **Replace**, which is why replace affects your data.\n</Accordion>\n<Accordion title=\"Why don't my preview changes show up in my published app?\">\nPreview and published app are **separate environments**. Changes you make in preview don't propagate to the live app until you re-publish or replace.\n</Accordion>\n<Accordion title=\"I saved my secret but nothing changed - what did I miss?\">\nSaving a secret isn't enough. A saved secret only takes effect in a published app after you **Re-publish** (re-publish).\n</Accordion>\n<Accordion title=\"I added a new secret/env variable - why isn't it taking effect?\">\nNew environment variables must be added to `.env` via the agent and then picked up by a **re-publish (Re-publish)**. An ordinary re-publish will pick up new `.env` keys.\n</Accordion>\n<Accordion title=\"How do I migrate my live database to my own external database?\">\nMigrating to your own database is a manual process: export your data, import it into your own Atlas instance, allowlist Emergent's egress IPs, update the `MONGO_URL` and `DB_NAME` system keys, then re-publish. There is no automatic background sync or cutover.\n</Accordion>\n<Accordion title=\"Is row-level security (RLS) available on MongoDB?\">\nMongoDB doesn't offer Postgres-style row-level security. Enforce per-user access rules in your app's API/query layer (scope every query to the authenticated user).\n</Accordion>\n</AccordionGroup>\n\n### GitHub\n\n<AccordionGroup>\n<Accordion title=\"How do I pull code from GitHub?\">\nUse **Save → Save to GitHub** (Standard plan and above) and clone locally. If you later re-import or let the agent work over pulled code, note the agent may change core files, keep a backup first.\n</Accordion>\n<Accordion title=\"I pushed to GitHub and my .env / credentials were exposed - how do I prevent this?\">\nNever commit secrets. Keep them in the **Secrets manager**, make sure `.env` is git-ignored before you Save to GitHub, and if anything leaked, rotate those keys at the provider immediately.\n</Accordion>\n</AccordionGroup>\n\n### Integrations\n\n<AccordionGroup>\n<Accordion title=\"How do I set up a third-party API - auth and keys?\">\nAsk the agent to add the integration, then store the API keys in the **Secrets manager** (never in code or GitHub) and re-publish so the published app picks them up.\n</Accordion>\n</AccordionGroup>\n\n### Security & privacy\n\n<AccordionGroup>\n<Accordion title=\"Where is my data stored? Is it private?\">\n\nYour data is processed and stored in the **United States and India**, access is limited, and it's governed by our DPA. Per-vendor processing locations are listed at [app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors). See **Data, Trust & Support → Where your data is stored**.\n</Accordion>\n<Accordion title=\"How does Emergent handle data leakage concerns?\">\n\nEach app has its own database and published app, and your data isn't used to train AI models (DPA 12.1). The main thing to manage on your side is secrets, keep them in the Secrets manager, never in GitHub. See **Data isolation & leakage**.\n</Accordion>\n<Accordion title=\"Do you have a signed Data Processing Agreement (DPA)?\">\n\nYes, it's **self-executing** and published at [app.emergent.sh/dpa](https://app.emergent.sh/dpa). It forms part of our Terms of Service, so no separate signature is needed. See **Data Processing Agreement (DPA)**.\n</Accordion>\n<Accordion title=\"How do I delete my account or erase all my personal data?\">\n\nDelete a single project via **Settings → Danger Zone** (permanent). Delete your whole account via **Account Settings** (cancels the subscription, removes published versions, reversible within the window). Within 45 days of termination you may instruct return or deletion of your personal data (DPA 14.3). See **Deletion & retention**.\n</Accordion>\n<Accordion title=\"Where is my data stored, and can I get EU-only hosting?\">\n\nData is stored in the **US and India**. EU-only hosting is **not available self-serve**, contact **privacy@emergent.sh** for feasibility and timing.\n</Accordion>\n</AccordionGroup>\n\n### Platform\n\n<AccordionGroup>\n<Accordion title=\"What is Emergent's uptime / where can I check platform status?\">\nCheck current platform status at the Trust Centre: [emergent.trust.site](https://emergent.trust.site).\n</Accordion>\n</AccordionGroup>","order":95,"parent_id":null,"icon":"help-circle","description":"As compiled in the FAQ Master tab of this workbook.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:33.220701+00:00","published_at":"2026-09-22T06:19:33.220701+00:00","published_content":"## Frequently Asked Questions\n\n<AccordionGroup>\n\n<Accordion title=\"What is Emergent?\">\nEmergent is an agentic vibe-coding platform where you describe an app in natural language and AI agents build, test, and publish it for you. You chat with the platform, refine your vision iteratively, and Emergent handles the implementation - front-end, back-end, database, hosting, and published app.\n</Accordion>\n\n<Accordion title=\"How does the chat-to-published app flow work?\">\nYou describe your app idea in the chat interface. Emergent's AI agents interpret your requirements, generate code, provision infrastructure, and publish a working application. You can refine and iterate by continuing the conversation. For a detailed walkthrough, see [The chat-to-published app flow](/the-chat-to-deployment-flow).\n</Accordion>\n\n<Accordion title=\"Do I need to know how to code?\">\nNo. Emergent is designed for users of all technical levels. You describe what you want in plain language, and the platform handles the technical implementation. If you *do* know how to code, you can also provide detailed technical guidance or even paste code snippets to steer the agents.\n</Accordion>\n\n<Accordion title=\"What types of applications can I build?\">\nEmergent supports a wide range of applications including web apps, mobile apps (iOS and Android via React Native), dashboards, APIs, SaaS tools, MVPs, prototypes, and internal business tools. The platform handles full-stack development with database integration, authentication, payments, and more.\n</Accordion>\n\n<Accordion title=\"Can I convert a web app to mobile or vice versa?\">\nYes. Emergent can convert web applications to React Native mobile apps and vice versa. The conversion process preserves your data and core functionality while adapting the UI and navigation patterns for the target platform. See [Web to Mobile conversion](/web-mobile-conversion-canonical) for details.\n</Accordion>\n\n<Accordion title=\"What technologies does Emergent use under the hood?\">\nEmergent builds apps using modern, production-ready stacks:\n\n- **Front-end:** React, Next.js, Tailwind CSS, shadcn/ui components\n- **Mobile:** React Native with Expo\n- **Back-end:** Python/FastAPI or Next.js API routes, REST APIs, running in Docker on Emergent's Kubernetes\n- **Database:** MongoDB Atlas (managed, scalable)\n- **Hosting:** Emergent's infrastructure (emergent.host, Cloudflare) for web; Expo Application Services for mobile\n- **Authentication:** Emergent Auth, or Auth0, Clerk, and other integrations\n- **Payments:** Stripe integration\n\nThe specific stack may vary based on your app's requirements.\n</Accordion>\n\n<Accordion title=\"How is my data stored and secured?\">\nData is stored in a MongoDB Atlas database provisioned for your project (shared cluster by default; a Dedicated Database is a paid upgrade). Each app gets its own isolated database with industry-standard encryption at rest and in transit. You own your data; note that production data export is not currently self-serve, use your own external DB or `mongodump` from an allowlisted machine after migration. See [Database (MongoDB)](/database-mongodb) for more.\n</Accordion>\n\n<Accordion title=\"Can I use my own API keys or bring my own LLM?\">\nYes. Emergent provides a [Universal LLM Key](/the-universal-llm-key) for convenience, but you can bring your own API keys for OpenAI, Anthropic, Google, or other providers. You can configure per-project LLM preferences and manage keys in your workspace settings.\n</Accordion>\n\n<Accordion title=\"How do I publish my app to production?\">\nClick **Publish** to publish your app for the first time (or **Re-publish** for subsequent publishes). The pipeline takes approximately 10-15 minutes and provisions hosting, configures environment variables, and makes your app live at your `<appname>.emergent.host` URL. You can also connect a [custom domain](/custom-domain) to your published app.\n</Accordion>\n\n<Accordion title=\"Why does Emergent say Publish instead of Deploy? Where did the Deploy button go?\">\nEmergent renamed deploying to publishing. **Deploy** and **Redeploy** are now **Publish** and **Re-publish**, deployments are called publishes, and the panel is **Manage Publishing**. Only the name changed - the process, your live apps, and your URLs are exactly the same. Older tutorials that say \"deploy\" still apply; just click Publish.\n</Accordion>\n\n<Accordion title=\"Can I connect a custom domain to my app?\">\nYes. Once your app is published, you can connect your own domain name through the workspace settings. Emergent handles DNS configuration and SSL certificate provisioning. See [Custom domain](/custom-domain) for step-by-step instructions.\n</Accordion>\n\n<Accordion title=\"What happens if I want to iterate or make changes after published app?\">\nContinue the conversation in chat. Describe the changes you want, and Emergent's agents will update the code, re-run tests, and publish the new version. Your database and user data persist across iterations.\n</Accordion>\n\n<Accordion title=\"Can I export my code and self-host?\">\nOn paid plans (Standard and above), you can push your application's source code to GitHub via the **Save → Save to GitHub** feature. There is no download/archive button; code leaves the platform via GitHub push or by copying from the VS Code view (available on all plans). You can then publish it to any hosting provider you choose.\n</Accordion>\n\n<Accordion title=\"Does Emergent support authentication and user management?\">\nYes. Emergent includes **Emergent Auth** (built-in), which supports email/password, Google sign-in (no extra keys needed), and phone OTP. You can also integrate Auth0, Clerk, or Firebase Auth. Ask the agent to add authentication to your app.\n</Accordion>\n\n<Accordion title=\"Can I integrate third-party APIs and services?\">\nAbsolutely. Tell Emergent which APIs or services you want to integrate (Stripe, Twilio, SendGrid, Google Maps, etc.), and the agents will generate the integration code, handle authentication, and configure environment variables.\n</Accordion>\n\n<Accordion title=\"How do I manage environment variables and secrets?\">\nEnvironment variables and secrets are managed through the workspace settings (**Preview → Manage → Secrets**). You can edit values of existing keys there. To add new keys, ask the agent to add them to `.env`, then re-publish. Secrets are encrypted and never exposed in the codebase.\n</Accordion>\n\n<Accordion title=\"What is the workspace and how do I navigate it?\">\nThe workspace is your project hub where you can view code, logs, database records, publish history, settings, and more. It provides a visual interface for monitoring and managing your app. See [A tour of the workspace](/a-tour-of-the-workspace) for a complete overview.\n</Accordion>\n\n<Accordion title=\"Can I collaborate with a team on an Emergent project?\">\nTeam collaboration features vary by plan. You can invite collaborators to view or edit projects, manage permissions, and work together in the same workspace. Check your plan details for collaboration limits.\n</Accordion>\n\n<Accordion title=\"What are the pricing plans and limits?\">\nEmergent offers multiple pricing tiers with different quotas for projects, published versions, compute, storage, and team members. Visit the Emergent pricing page or your account dashboard for the latest plan details and limits.\n</Accordion>\n\n<Accordion title=\"How do I upgrade or downgrade my plan?\">\nYou can change your subscription tier at any time from the billing section of your account settings. Upgrades take effect immediately; downgrades apply at the end of the current billing cycle.\n</Accordion>\n\n<Accordion title=\"What happens if I hit a usage limit?\">\nIf you reach a plan limit (projects, API calls, storage, etc.), you'll receive a notification. Depending on the limit, the platform may pause certain operations until you upgrade or the next billing cycle begins. Critical functionality like accessing your code and data remains available.\n</Accordion>\n\n<Accordion title=\"Can I cancel my subscription at any time?\">\nYes. You can cancel your subscription from the billing settings. Your access continues until the end of the current billing period, after which your account transitions to the Free plan.\n</Accordion>\n\n<Accordion title=\"What support options are available?\">\nSupport options depend on your plan. All users have access to documentation, in-app live chat (Emmy, primary/fastest), Discord community, and email support at support@emergent.sh.\n\nHigher-tier plans may include priority support or forward published engineers.\n</Accordion>\n\n<Accordion title=\"How do I report a bug or request a feature?\">\n\nUse the feedback widget in the workspace, or contact support via email at support@emergent.sh. Feature requests are tracked and prioritized based on user demand. You can also join the Emergent community to vote on and discuss upcoming features.\n</Accordion>\n\n<Accordion title=\"Is there a limit to how many times I can iterate on an app?\">\nIteration limits depend on your plan. Most plans allow unlimited iterations within reasonable usage bounds. Compute-intensive operations (like full re-builds) may count toward usage quotas.\n</Accordion>\n\n<Accordion title=\"Can I build apps in languages other than English?\">\nYes. Emergent supports natural-language input in multiple languages. You can describe your app in your preferred language, and the platform will generate code and content accordingly.\n</Accordion>\n\n<Accordion title=\"Does Emergent support internationalization (i18n) in apps?\">\nYes. You can request multi-language support for your app, and Emergent will generate i18n-ready code with locale management, translation keys, and language switchers.\n</Accordion>\n\n<Accordion title=\"What testing does Emergent perform on my app?\">\nEmergent's agents run automated tests during the build process, including unit tests, integration tests, and basic end-to-end smoke tests. You can also request additional test coverage or specific testing scenarios.\n</Accordion>\n\n<Accordion title=\"Can I access the database directly?\">\nYou can query and manage your MongoDB database through the Database Manager in the workspace interface. External MongoDB client connections are not supported, the managed cluster rejects external connections. All browsing and editing must be done via the Database Manager (note: it edits live data with no undo).\n</Accordion>\n\n<Accordion title=\"How do I back up my database?\">\nThe platform manages backups automatically. There is no Atlas console access for configuring additional backup policies. You can migrate your data to your own external database using the manual runbook (export → import → allowlist Emergent's egress IPs → update `MONGO_URL`/`DB_NAME` → re-publish) if you need more control.\n</Accordion>\n\n<Accordion title=\"What happens to my data if I delete a project?\">\n<Warning>\nDeleting a project permanently removes the codebase, database, and all associated resources. This action cannot be undone. Always export your code and data before deletion.\n</Warning>\n</Accordion>\n\n<Accordion title=\"Can I import an existing codebase into Emergent?\">\nYes. You can import an existing codebase when starting a new job, connect your GitHub account (OAuth), provide a public URL, or ask the agent. Note that importing is only available at new-job creation; there is no mid-job pull or in-platform sync.\n</Accordion>\n\n<Accordion title=\"Does Emergent support mobile app store published app?\">\nYes. For React Native apps, Emergent integrates with Expo Application Services (EAS) to build and submit apps to the Apple App Store and Google Play Store. You'll need developer accounts with Apple and Google.\n</Accordion>\n\n<Accordion title=\"How do I handle app updates after publishing to app stores?\">\nContinue iterating in Emergent as usual. When you're ready to release an update, Emergent can rebuild and submit the new version through EAS. You control the release schedule and versioning.\n</Accordion>\n\n<Accordion title=\"What are the system requirements for using Emergent?\">\nEmergent is a cloud-based platform accessible via any modern web browser (Chrome, Firefox, Safari, Edge). No local installation or specific hardware is required. For mobile app testing, you can use simulators (included) or physical devices.\n</Accordion>\n\n<Accordion title=\"Can I use Emergent offline?\">\nNo. Emergent is a cloud platform that requires an internet connection for the AI agents to build, test, and publish your apps.\n</Accordion>\n\n<Accordion title=\"Where can I learn more about Emergent-specific terminology?\">\nSee the [Glossary of Emergent terms](/glossary-of-emergent-terms) for definitions of platform-specific concepts like agents, vibes, canonical builds, and more.\n</Accordion>\n\n<Accordion title=\"How does Emergent handle versioning and rollbacks?\">\n\nEmergent maintains a publish history in the workspace. You can view past versions and roll back to one of up to 3 previous images if needed. Each published app is tagged with a timestamp.\n\nEach published app is tagged with a changelog.\n</Accordion>\n\n<Accordion title=\"Can I schedule published versions or automate workflows?\">\nAdvanced automation features (like scheduled published versions or CI/CD integrations) may be available on higher-tier plans or through API access. Check your plan details or contact support for specifics.\n</Accordion>\n\n<Accordion title=\"What happens if an agent makes a mistake or breaks my app?\">\nEmergent agents are designed to test and validate changes before published app. If an issue occurs, you can roll back to a previous version, describe the problem in chat, and the agents will attempt to fix it. You can also manually edit code in the workspace.\n</Accordion>\n\n<Accordion title=\"Is my intellectual property protected?\">\nYes. You retain full ownership of the applications and content you create with Emergent. Emergent does not claim ownership of your ideas, code, or data.\n</Accordion>\n\n<Accordion title=\"Does Emergent comply with data protection regulations (GDPR, etc.)?\">\n\nEmergent follows industry best practices for data security and privacy. For specific compliance questions or data processing agreements, contact the Emergent legal or support team.\n</Accordion>\n\n<Accordion title=\"Can I white-label or resell apps built on Emergent?\">\nYes. You own the apps you build and can white-label, resell, or commercialize them as you see fit. Check your plan's terms of service for any restrictions.\n</Accordion>\n\n</AccordionGroup>\n\n---\n\n<Callout type=\"info\" title=\"Still have questions?\">\nIf your question isn't answered here, check the rest of the documentation or reach out to Emergent support. We're here to help you succeed.\n</Callout>\n\n---\n\n## Common questions by topic\n\n### Prompting\n\n<AccordionGroup>\n<Accordion title=\"Why doesn't pasting my ChatGPT plan/spec produce what I expect?\">\nAn external spec written for another tool often doesn't map to Emergent's build flow. Emergent works best when you describe features conversationally and let the agent ask clarifying questions, rather than dropping in a large pre-written plan. Break the plan into smaller feature requests and iterate.\n</Accordion>\n<Accordion title=\"How should I phrase prompts to get better results?\">\nSmall, concise feature requests beat mega-prompts, they lower credit burn and reduce confusion. Describe one capability at a time, answer the agent's clarifying questions (Universal Key vs your own key, auth, design preferences), and refine step by step.\n</Accordion>\n</AccordionGroup>\n\n### Models & agent quality\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between E1, E2, E3 and the underlying models?\">\nE1, E2 and E3 are Emergent's agent tiers (different workflows), chosen from the agent dropdown at job creation; the LLM is a separate model selector. They differ in capability and cost, higher tiers apply more reasoning to complex work. Pick the tier that matches how hard your task is.\n</Accordion>\n<Accordion title=\"What is Maxx mode and how does it affect credit consumption?\">\nMaxx mode (Pro-only) runs the agent at higher effort for tougher tasks and, as a result, consumes significantly more credits. Use it when standard runs get stuck.\n</Accordion>\n</AccordionGroup>\n\n### Credits\n\n<AccordionGroup>\n<Accordion title=\"How are credits deducted and what makes an app consume more?\">\nCredits are consumed by generation, testing, cloud publishes and integrations. App complexity and Maxx mode drive higher usage.\n</Accordion>\n<Accordion title=\"How much does a single prompt cost in credits?\">\nIt varies with the work the agent does. You can set a limit to cap consumption so a single prompt can't run away.\n</Accordion>\n<Accordion title=\"Do my credits expire? When do they reset?\">\nMonthly subscription credits do not roll over, they refill to the cap at each billing cycle. Purchased top-up credits never expire. Promotional/boost credits carry a shown expiry date. Free tier users receive 10 credits on their first day.\n</Accordion>\n<Accordion title=\"What happens if I run low on credits mid-prompt?\">\nThe build pauses when credits run out; top up to continue. A published app charge can take an already-at-or-below-zero balance negative; jobs pause at zero and there is no separate renewal takedown threshold.\n</Accordion>\n<Accordion title=\"What are the different types of credits (Universal Key vs Emergent credits)?\">\n**Emergent Credits** pay for building on the platform. The **Universal LLM Key** uses Emergent Credits to call GPT / Claude / Gemini without setting up your own API key. You can top up either at any time, just don't confuse the two.\n</Accordion>\n</AccordionGroup>\n\n### Plans\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between Standard and Pro?\">\nThe Free plan provides daily credit grants (10 on day one) but cannot publish. Standard and Pro differ in included credits and features; Pro adds more capability. See the Plans & billing pages for the current breakdown.\n</Accordion>\n<Accordion title=\"Which publishing plan do I need (how much CPU/memory)?\">\nPublishing tiers are Starter, Launch, Grow, Scale, and Elite, each a fixed monthly credit fee with increasing CPU/memory. Pick the tier that matches your app's resource needs; you can move up if it runs hot.\n</Accordion>\n</AccordionGroup>\n\n### Prompt windows\n\n<AccordionGroup>\n<Accordion title=\"Which prompt window should I use - Fullstack, Mobile, Landing page, or Brainstorm?\">\nUse **Fullstack Builder** for full web apps, **Mobile App** for native iOS/Android apps, **Landing Page** for marketing pages, and **Brainstorm** to plan an idea before building. See \"Compare the 4 windows\".\n</Accordion>\n<Accordion title=\"What are the limitations specific to each job type (mobile vs web)?\">\nA native **Mobile App** runs on a different stack underneath, it is **not** a web URL in a wrapper, which changes its domain, bundle-ID and publishing behaviour. **Web** apps publish to a URL and use re-publish/replace.\n</Accordion>\n</AccordionGroup>\n\n### Mobile\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between a native mobile app and a web URL?\">\nA native app is compiled for iOS/Android and installed from the app stores; a web app is a URL you open in a browser. Native apps have no domain attached.\n</Accordion>\n<Accordion title=\"Is there a step-by-step guide to publish to the Play Store / App Store?\">\nYes. Preview and test on-device, generate a build, then publish to the stores. See the mobile publishing guide for the per-platform steps and review timelines.\n</Accordion>\n<Accordion title=\"What are package name, bundle ID and app ID - and why can't I change them after the first build?\">\nThey identify your app to Android (package name) and iOS (bundle ID). They are generated at the first build/publish and **locked** afterwards, so plan them before your first build.\n</Accordion>\n<Accordion title=\"Why did my integration (e.g. Apple Music) break after publishing?\">\nAn integration must use the **same bundle ID** as your app. If the bundle ID configured with the provider doesn't match your app's, the integration breaks.\n</Accordion>\n</AccordionGroup>\n\n### Web ↔ Mobile\n\n<AccordionGroup>\n<Accordion title=\"Will I lose data or functionality when converting between web and mobile?\">\nConverting adapts the UI and navigation for the target platform while preserving your data and core functionality. Mobile uses the same backend database as your web app.\n</Accordion>\n</AccordionGroup>\n\n### Custom domain\n\n<AccordionGroup>\n<Accordion title=\"My custom domain is stuck / not loading - how do I fix it?\">\nMost cases are a DNS fix: add an **A record** pointing to the Emergent IP shown in the Custom Domain flow, plus a **CNAME `www`** entry with your domain value. Give DNS time to propagate. (Web apps only.)\n</Accordion>\n<Accordion title=\"Do I need a custom domain for a mobile app?\">\nNo. Native mobile apps have no domain attached, so there's nothing to buy.\n</Accordion>\n<Accordion title=\"What is the emergent subdomain (www.app...) and will it work?\">\nEvery web app gets a built-in Emergent subdomain (`<appname>.emergent.host`) that works as-is. Default subdomains cannot be renamed. A custom domain is optional, add one when you want your own branded URL.\n</Accordion>\n</AccordionGroup>\n\n### Changing your app's name\n\n<AccordionGroup>\n<Accordion title=\"Can I change the name of my app on the emergent domain?\">\nThe default Emergent subdomain (`<appname>.emergent.host`) cannot be changed. To use a different name, add a custom domain; the built-in subdomain itself is fixed.\n</Accordion>\n<Accordion title='Google auth shows \"login to xyz\" but I want it to say something else - why?'>\nThat consent-screen name comes from the OAuth app configured with Google, not from Emergent. Update the app name in your Google OAuth (Google Cloud) credentials and the screen will follow.\n</Accordion>\n</AccordionGroup>\n\n### Published app\n\n<AccordionGroup>\n<Accordion title=\"What is the difference between re-publish and replace published app?\">\n**Re-publish** (**Re-publish**) pushes your latest code to the live app free of charge  and picks up any new environment variable keys added to `.env`. **Replace** pushes code and can also swap the production database.\n</Accordion>\n<Accordion title='Why does my database only change when I use \"replace\"?'>\nRe-publish keeps your existing production database untouched. The production database only changes when you **Replace**, which is why replace affects your data.\n</Accordion>\n<Accordion title=\"Why don't my preview changes show up in my published app?\">\nPreview and published app are **separate environments**. Changes you make in preview don't propagate to the live app until you re-publish or replace.\n</Accordion>\n<Accordion title=\"I saved my secret but nothing changed - what did I miss?\">\nSaving a secret isn't enough. A saved secret only takes effect in a published app after you **Re-publish** (re-publish).\n</Accordion>\n<Accordion title=\"I added a new secret/env variable - why isn't it taking effect?\">\nNew environment variables must be added to `.env` via the agent and then picked up by a **re-publish (Re-publish)**. An ordinary re-publish will pick up new `.env` keys.\n</Accordion>\n<Accordion title=\"How do I migrate my live database to my own external database?\">\nMigrating to your own database is a manual process: export your data, import it into your own Atlas instance, allowlist Emergent's egress IPs, update the `MONGO_URL` and `DB_NAME` system keys, then re-publish. There is no automatic background sync or cutover.\n</Accordion>\n<Accordion title=\"Is row-level security (RLS) available on MongoDB?\">\nMongoDB doesn't offer Postgres-style row-level security. Enforce per-user access rules in your app's API/query layer (scope every query to the authenticated user).\n</Accordion>\n</AccordionGroup>\n\n### GitHub\n\n<AccordionGroup>\n<Accordion title=\"How do I pull code from GitHub?\">\nUse **Save → Save to GitHub** (Standard plan and above) and clone locally. If you later re-import or let the agent work over pulled code, note the agent may change core files, keep a backup first.\n</Accordion>\n<Accordion title=\"I pushed to GitHub and my .env / credentials were exposed - how do I prevent this?\">\nNever commit secrets. Keep them in the **Secrets manager**, make sure `.env` is git-ignored before you Save to GitHub, and if anything leaked, rotate those keys at the provider immediately.\n</Accordion>\n</AccordionGroup>\n\n### Integrations\n\n<AccordionGroup>\n<Accordion title=\"How do I set up a third-party API - auth and keys?\">\nAsk the agent to add the integration, then store the API keys in the **Secrets manager** (never in code or GitHub) and re-publish so the published app picks them up.\n</Accordion>\n</AccordionGroup>\n\n### Security & privacy\n\n<AccordionGroup>\n<Accordion title=\"Where is my data stored? Is it private?\">\n\nYour data is processed and stored in the **United States and India**, access is limited, and it's governed by our DPA. Per-vendor processing locations are listed at [app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors). See **Data, Trust & Support → Where your data is stored**.\n</Accordion>\n<Accordion title=\"How does Emergent handle data leakage concerns?\">\n\nEach app has its own database and published app, and your data isn't used to train AI models (DPA 12.1). The main thing to manage on your side is secrets, keep them in the Secrets manager, never in GitHub. See **Data isolation & leakage**.\n</Accordion>\n<Accordion title=\"Do you have a signed Data Processing Agreement (DPA)?\">\n\nYes, it's **self-executing** and published at [app.emergent.sh/dpa](https://app.emergent.sh/dpa). It forms part of our Terms of Service, so no separate signature is needed. See **Data Processing Agreement (DPA)**.\n</Accordion>\n<Accordion title=\"How do I delete my account or erase all my personal data?\">\n\nDelete a single project via **Settings → Danger Zone** (permanent). Delete your whole account via **Account Settings** (cancels the subscription, removes published versions, reversible within the window). Within 45 days of termination you may instruct return or deletion of your personal data (DPA 14.3). See **Deletion & retention**.\n</Accordion>\n<Accordion title=\"Where is my data stored, and can I get EU-only hosting?\">\n\nData is stored in the **US and India**. EU-only hosting is **not available self-serve**, contact **privacy@emergent.sh** for feasibility and timing.\n</Accordion>\n</AccordionGroup>\n\n### Platform\n\n<AccordionGroup>\n<Accordion title=\"What is Emergent's uptime / where can I check platform status?\">\nCheck current platform status at the Trust Centre: [emergent.trust.site](https://emergent.trust.site).\n</Accordion>\n</AccordionGroup>","published_title":"FAQs","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"104de3fe-a128-4d4b-9dc2-3fd457ffcb3b","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Getting help, support & community","slug":"getting-help-support-community","content":"## Where to get help\n\nWe're here to help you succeed with Emergent. Whether you have a question, need troubleshooting support, or want to connect with other builders, you have two main channels.\n\n### Discord community\n\nJoin our [Discord server](https://discord.gg/emergent) to:\n\n- Ask questions and get quick answers from the community\n- Share what you're building and get feedback\n- Learn tips and workflows from experienced users\n- Stay up to date with platform announcements\n\nThe Discord is the fastest way to connect with both the Emergent team and other builders.\n\n### Support email\n\nFor issues that require account-level assistance or private discussion, email us at **support@emergent.sh**.\n\nWe typically respond within one business day. Support email is best for:\n\n- Billing and subscription questions\n- Account access issues\n- Detailed bug reports\n- Feature requests that include sensitive information\n\n---\n\n## Filing a good bug report\n\nWhen something goes wrong, a detailed bug report helps us fix the issue quickly. The most important piece of information is your **Job ID**.\n\n### Include your Job ID\n\nEvery build or operation in Emergent has a unique Job ID visible in the workspace. To find it:\n\n<Steps>\n<Step title=\"Locate the Job ID\">\nLook in the bottom-left corner of the workspace sidebar or in the job history panel. It's a string like `job_abc123xyz`.\n</Step>\n\n<Step title=\"Copy the full ID\">\nClick to copy or select and copy the entire Job ID string.\n</Step>\n\n<Step title=\"Include it in your report\">\nPaste the Job ID in your Discord message or support email. This lets us look up the exact context of your build.\n</Step>\n</Steps>\n\n<Tip>\nIf you have multiple jobs related to the issue, include all relevant Job IDs.\n</Tip>\n\n### Add screenshots of errors\n\nA screenshot of the error message or unexpected behavior provides critical context. Capture:\n\n- The full error message text\n- Any red error banners or console output\n- The state of the workspace when the issue occurred\n\n### Describe what you expected vs. what happened\n\nA quick sentence or two helps us understand the gap:\n\n> \"I asked the agent to add a login page, expected it to create `/login`, but it created `/signin` instead and broke the routing.\"\n\nThis context, combined with your Job ID and screenshot, gives us everything we need to investigate.\n\n---\n\n<Info title=\"Learning resources\">\nIf you're new to Emergent, check out [Your first build](/start-with-your-idea) for a guided walkthrough, or visit [How apps work here](/how-apps-work-here-mental-model) to understand the platform's mental model.\n</Info>\n","order":99,"parent_id":null,"icon":"mail","description":"1. Where to get help: Discord community, support email.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:36.774342+00:00","published_at":"2026-09-22T06:19:36.774342+00:00","published_content":"## Where to get help\n\nWe're here to help you succeed with Emergent. Whether you have a question, need troubleshooting support, or want to connect with other builders, you have two main channels.\n\n### Discord community\n\nJoin our [Discord server](https://discord.gg/emergent) to:\n\n- Ask questions and get quick answers from the community\n- Share what you're building and get feedback\n- Learn tips and workflows from experienced users\n- Stay up to date with platform announcements\n\nThe Discord is the fastest way to connect with both the Emergent team and other builders.\n\n### Support email\n\nFor issues that require account-level assistance or private discussion, email us at **support@emergent.sh**.\n\nWe typically respond within one business day. Support email is best for:\n\n- Billing and subscription questions\n- Account access issues\n- Detailed bug reports\n- Feature requests that include sensitive information\n\n---\n\n## Filing a good bug report\n\nWhen something goes wrong, a detailed bug report helps us fix the issue quickly. The most important piece of information is your **Job ID**.\n\n### Include your Job ID\n\nEvery build or operation in Emergent has a unique Job ID visible in the workspace. To find it:\n\n<Steps>\n<Step title=\"Locate the Job ID\">\nLook in the bottom-left corner of the workspace sidebar or in the job history panel. It's a string like `job_abc123xyz`.\n</Step>\n\n<Step title=\"Copy the full ID\">\nClick to copy or select and copy the entire Job ID string.\n</Step>\n\n<Step title=\"Include it in your report\">\nPaste the Job ID in your Discord message or support email. This lets us look up the exact context of your build.\n</Step>\n</Steps>\n\n<Tip>\nIf you have multiple jobs related to the issue, include all relevant Job IDs.\n</Tip>\n\n### Add screenshots of errors\n\nA screenshot of the error message or unexpected behavior provides critical context. Capture:\n\n- The full error message text\n- Any red error banners or console output\n- The state of the workspace when the issue occurred\n\n### Describe what you expected vs. what happened\n\nA quick sentence or two helps us understand the gap:\n\n> \"I asked the agent to add a login page, expected it to create `/login`, but it created `/signin` instead and broke the routing.\"\n\nThis context, combined with your Job ID and screenshot, gives us everything we need to investigate.\n\n---\n\n<Info title=\"Learning resources\">\nIf you're new to Emergent, check out [Your first build](/start-with-your-idea) for a guided walkthrough, or visit [How apps work here](/how-apps-work-here-mental-model) to understand the platform's mental model.\n</Info>\n","published_title":"Getting help, support & community","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"70041119-1b75-4153-b65d-1da477092609","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Account security & login","slug":"account-security-login","content":"## Sign-in methods\n\nEmergent supports five authentication methods to fit your workflow:\n\n- **Email + password** - traditional username/password sign-in.\n- **Google OAuth** - fast login with your Google account (see [Google auth](/google-auth) for configuration).\n- **Apple OAuth** - secure sign-in with Apple ID.\n- **Phone OTP** - SMS one-time passcode authentication (carrier rates apply).\n- **SSO** - SAML or OpenID Connect for enterprise teams (Pro/Enterprise plans).\n\nYou can link multiple providers to the same Emergent account by signing in with each method while already authenticated. Once linked, any method grants access to your workspace.\n\n<Tip title=\"Switching providers\">\nIf you signed up with email but want to use Google going forward, sign in with your email, then visit **Settings → Account → Connected accounts** and authorize Google. Both methods will then unlock the same workspace.\n</Tip>\n\n## Resetting your password\n\n<Steps>\n<Step title=\"Navigate to the sign-in screen\">\nClick **Sign In** from the Emergent homepage.\n</Step>\n\n<Step title=\"Request a reset link\">\nSelect **Forgot password?** below the email field. Enter your email address and submit.\n</Step>\n\n<Step title=\"Check your inbox\">\nYou'll receive a password-reset email within a few minutes (check spam if it doesn't arrive). The link expires after **24 hours**.\n</Step>\n\n<Step title=\"Set a new password\">\nClick the link, enter a new password (minimum 8 characters), and confirm. You'll be signed in automatically.\n</Step>\n</Steps>\n\n<Note>\nPassword reset is only available for accounts that signed up with **email + password**. OAuth accounts (Google, Apple) inherit security from the identity provider and do not have Emergent passwords.\n</Note>\n\n## Changing your email address\n\nEmail addresses cannot be changed once an account is created. This immutability ensures audit integrity, billing consistency, and prevents accidental email collisions in team workspaces.\n\n### Workaround: GitHub migration\n\nIf you must switch to a new email:\n\n1. Export any critical projects or data you want to preserve.\n2. Create a new Emergent account with the desired email address.\n3. Transfer projects manually by cloning repositories or re-importing app definitions.\n\n<Warning title=\"Team seats and billing\">\nDeleting your old account and re-joining a team will consume a new seat. Contact [support@emergent.sh](mailto:support@emergent.sh) if you need help coordinating a migration with minimal disruption.\n</Warning>\n\n## Deleting your account\n\nAccount deletion is irreversible but includes a **45-day grace period** during which your account is soft-deleted and can be restored.\n\n<Steps>\n<Step title=\"Navigate to account settings\">\nClick your avatar → **Settings → Account**.\n</Step>\n\n<Step title=\"Request deletion\">\nScroll to **Danger zone** and select **Delete account**. Confirm your password (or re-authenticate via OAuth).\n</Step>\n\n<Step title=\"Grace period begins\">\nYour account is immediately deactivated. All apps, projects, and data are hidden but retained for **45 days**.\n</Step>\n\n<Step title=\"Restore or purge\">\nDuring the grace period you can sign in to restore your account with one click. After 45 days all data is permanently purged and cannot be recovered.\n</Step>\n</Steps>\n\n<Danger title=\"Permanent data loss\">\nAfter the 45-day grace period, deletion is final. Export any critical projects, code, or databases **before** initiating deletion. See [Database (MongoDB)](/database-mongodb) for export instructions.\n</Danger>\n\n### What happens to team workspaces?\n\n- If you are the **sole owner**, the workspace is also soft-deleted. Transfer ownership to another member before deletion to preserve team resources.\n- If you are a **member**, you are simply removed. The workspace and its apps remain unaffected.\n\n## Session and token security\n\nEmergent uses industry-standard session management to protect your account:\n\n| Feature | Detail |\n|---------|--------|\n| **Session duration** | 30 days of inactivity before auto-logout |\n| **Token storage** | Secure HTTP-only cookies; tokens are never exposed to client JavaScript |\n| **Token rotation** | Refresh tokens rotate on every use; stolen tokens expire within minutes |\n| **Device tracking** | Active sessions are listed in **Settings → Security** with IP, browser, and last-seen timestamp |\n| **Remote logout** | Revoke any session remotely (useful if you left a device signed in) |\n\n<Info>\nEmergent does **not** store plaintext passwords. All credentials are hashed with bcrypt (cost factor 12) and OAuth providers never share passwords with our platform.\n</Info>\n\n### Revoking sessions\n\n<Steps>\n<Step title=\"Open security settings\">\nClick your avatar → **Settings → Security → Active sessions**.\n</Step>\n\n<Step title=\"Review devices\">\nEach row shows a device fingerprint, browser, IP address, and last activity timestamp.\n</Step>\n\n<Step title=\"Revoke unwanted sessions\">\nClick **Revoke** next to any session you don't recognize or no longer use. That device will be logged out immediately.\n</Step>\n</Steps>\n\n<Tip title=\"Sign out everywhere\">\nIf you suspect unauthorized access, use **Sign out all other sessions** at the top of the list to invalidate every session except your current one. Change your password immediately afterward.\n</Tip>\n\n## Best practices\n\n- **Enable two-factor authentication** (2FA) if your OAuth provider supports it (Google, Apple both do). Emergent inherits 2FA from the identity provider.\n- **Review active sessions monthly**, especially if you use shared or public computers.\n- **Use a password manager** for strong, unique passwords on email-based accounts.\n- **Link multiple sign-in methods** so you have a backup if one provider is unavailable.\n\n<AccordionGroup>\n<Accordion title=\"Can I require 2FA for my entire team workspace?\">\nYes, on **Enterprise plans**. Contact [support@emergent.sh](mailto:support@emergent.sh) to enable organization-wide 2FA enforcement. Members without 2FA will be prompted to configure it on their next sign-in.\n</Accordion>\n\n<Accordion title=\"What happens if I lose access to my OAuth provider?\">\nIf you've linked multiple sign-in methods, use an alternate provider. If OAuth is your only method and you lose access, contact [support@emergent.sh](mailto:support@emergent.sh) with proof of ownership (billing receipts, project metadata) to regain access.\n</Accordion>\n\n<Accordion title=\"Are API tokens covered by the same security policies?\">\nYes. Personal access tokens (PATs) for the Emergent API follow the same rotation and expiry rules. Review and rotate tokens in **Settings → Developer → API tokens**. Tokens are scoped to specific permissions and can be revoked individually. See [The Universal LLM Key](/the-universal-llm-key) for more on API security.\n</Accordion>\n</AccordionGroup>\n","order":100,"parent_id":null,"icon":"lock","description":"Sign-in methods (email/Google/Apple/phone-OTP/SSO), password reset, why email can't be changed (+ GitHub workaround), account deletion with 45-day grace, and session/token security","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:37.902531+00:00","published_at":"2026-09-22T06:19:37.902531+00:00","published_content":"## Sign-in methods\n\nEmergent supports five authentication methods to fit your workflow:\n\n- **Email + password** - traditional username/password sign-in.\n- **Google OAuth** - fast login with your Google account (see [Google auth](/google-auth) for configuration).\n- **Apple OAuth** - secure sign-in with Apple ID.\n- **Phone OTP** - SMS one-time passcode authentication (carrier rates apply).\n- **SSO** - SAML or OpenID Connect for enterprise teams (Pro/Enterprise plans).\n\nYou can link multiple providers to the same Emergent account by signing in with each method while already authenticated. Once linked, any method grants access to your workspace.\n\n<Tip title=\"Switching providers\">\nIf you signed up with email but want to use Google going forward, sign in with your email, then visit **Settings → Account → Connected accounts** and authorize Google. Both methods will then unlock the same workspace.\n</Tip>\n\n## Resetting your password\n\n<Steps>\n<Step title=\"Navigate to the sign-in screen\">\nClick **Sign In** from the Emergent homepage.\n</Step>\n\n<Step title=\"Request a reset link\">\nSelect **Forgot password?** below the email field. Enter your email address and submit.\n</Step>\n\n<Step title=\"Check your inbox\">\nYou'll receive a password-reset email within a few minutes (check spam if it doesn't arrive). The link expires after **24 hours**.\n</Step>\n\n<Step title=\"Set a new password\">\nClick the link, enter a new password (minimum 8 characters), and confirm. You'll be signed in automatically.\n</Step>\n</Steps>\n\n<Note>\nPassword reset is only available for accounts that signed up with **email + password**. OAuth accounts (Google, Apple) inherit security from the identity provider and do not have Emergent passwords.\n</Note>\n\n## Changing your email address\n\nEmail addresses cannot be changed once an account is created. This immutability ensures audit integrity, billing consistency, and prevents accidental email collisions in team workspaces.\n\n### Workaround: GitHub migration\n\nIf you must switch to a new email:\n\n1. Export any critical projects or data you want to preserve.\n2. Create a new Emergent account with the desired email address.\n3. Transfer projects manually by cloning repositories or re-importing app definitions.\n\n<Warning title=\"Team seats and billing\">\nDeleting your old account and re-joining a team will consume a new seat. Contact [support@emergent.sh](mailto:support@emergent.sh) if you need help coordinating a migration with minimal disruption.\n</Warning>\n\n## Deleting your account\n\nAccount deletion is irreversible but includes a **45-day grace period** during which your account is soft-deleted and can be restored.\n\n<Steps>\n<Step title=\"Navigate to account settings\">\nClick your avatar → **Settings → Account**.\n</Step>\n\n<Step title=\"Request deletion\">\nScroll to **Danger zone** and select **Delete account**. Confirm your password (or re-authenticate via OAuth).\n</Step>\n\n<Step title=\"Grace period begins\">\nYour account is immediately deactivated. All apps, projects, and data are hidden but retained for **45 days**.\n</Step>\n\n<Step title=\"Restore or purge\">\nDuring the grace period you can sign in to restore your account with one click. After 45 days all data is permanently purged and cannot be recovered.\n</Step>\n</Steps>\n\n<Danger title=\"Permanent data loss\">\nAfter the 45-day grace period, deletion is final. Export any critical projects, code, or databases **before** initiating deletion. See [Database (MongoDB)](/database-mongodb) for export instructions.\n</Danger>\n\n### What happens to team workspaces?\n\n- If you are the **sole owner**, the workspace is also soft-deleted. Transfer ownership to another member before deletion to preserve team resources.\n- If you are a **member**, you are simply removed. The workspace and its apps remain unaffected.\n\n## Session and token security\n\nEmergent uses industry-standard session management to protect your account:\n\n| Feature | Detail |\n|---------|--------|\n| **Session duration** | 30 days of inactivity before auto-logout |\n| **Token storage** | Secure HTTP-only cookies; tokens are never exposed to client JavaScript |\n| **Token rotation** | Refresh tokens rotate on every use; stolen tokens expire within minutes |\n| **Device tracking** | Active sessions are listed in **Settings → Security** with IP, browser, and last-seen timestamp |\n| **Remote logout** | Revoke any session remotely (useful if you left a device signed in) |\n\n<Info>\nEmergent does **not** store plaintext passwords. All credentials are hashed with bcrypt (cost factor 12) and OAuth providers never share passwords with our platform.\n</Info>\n\n### Revoking sessions\n\n<Steps>\n<Step title=\"Open security settings\">\nClick your avatar → **Settings → Security → Active sessions**.\n</Step>\n\n<Step title=\"Review devices\">\nEach row shows a device fingerprint, browser, IP address, and last activity timestamp.\n</Step>\n\n<Step title=\"Revoke unwanted sessions\">\nClick **Revoke** next to any session you don't recognize or no longer use. That device will be logged out immediately.\n</Step>\n</Steps>\n\n<Tip title=\"Sign out everywhere\">\nIf you suspect unauthorized access, use **Sign out all other sessions** at the top of the list to invalidate every session except your current one. Change your password immediately afterward.\n</Tip>\n\n## Best practices\n\n- **Enable two-factor authentication** (2FA) if your OAuth provider supports it (Google, Apple both do). Emergent inherits 2FA from the identity provider.\n- **Review active sessions monthly**, especially if you use shared or public computers.\n- **Use a password manager** for strong, unique passwords on email-based accounts.\n- **Link multiple sign-in methods** so you have a backup if one provider is unavailable.\n\n<AccordionGroup>\n<Accordion title=\"Can I require 2FA for my entire team workspace?\">\nYes, on **Enterprise plans**. Contact [support@emergent.sh](mailto:support@emergent.sh) to enable organization-wide 2FA enforcement. Members without 2FA will be prompted to configure it on their next sign-in.\n</Accordion>\n\n<Accordion title=\"What happens if I lose access to my OAuth provider?\">\nIf you've linked multiple sign-in methods, use an alternate provider. If OAuth is your only method and you lose access, contact [support@emergent.sh](mailto:support@emergent.sh) with proof of ownership (billing receipts, project metadata) to regain access.\n</Accordion>\n\n<Accordion title=\"Are API tokens covered by the same security policies?\">\nYes. Personal access tokens (PATs) for the Emergent API follow the same rotation and expiry rules. Review and rotate tokens in **Settings → Developer → API tokens**. Tokens are scoped to specific permissions and can be revoked individually. See [The Universal LLM Key](/the-universal-llm-key) for more on API security.\n</Accordion>\n</AccordionGroup>\n","published_title":"Account security & login","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"0c60cc39-4964-42c9-8d26-4d02ca40ac13","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"App takedown & content moderation","slug":"app-takedown-content-moderation","content":"## Why apps are sometimes taken down\n\nEmergent runs automated content-policy and phishing screening on all published apps to keep the platform safe and trustworthy for everyone. If an app triggers these filters - even by mistake - it may be automatically taken offline.\n\n<Callout type=\"info\" title=\"False positives happen\">\nAutomated moderation occasionally flags legitimate apps. We provide a simple dispute and recovery path so you're never permanently locked out of your work.\n</Callout>\n\nCommon triggers include:\n\n- Phishing keywords or suspicious login flows (e.g. credential harvesting forms)\n- Malicious content or content-policy violations (harassment, spam, illegal material)\n- Impersonation of well-known brands or services\n- Misleading or deceptive UI patterns\n\n## What happens when your app is flagged\n\n1. **Immediate takedown:** The live published app is removed from public access; the public URL returns a `403 Forbidden` or takedown notice.\n2. **Notification:** You receive an email and in-workspace alert explaining the reason for takedown.\n3. **Source code remains safe:** Your workspace, chat history, and code are **not deleted** - only the public published app is affected.\n\n<Warning>\nYour credits are **not** refunded for apps taken down after published app. The published app consumed platform resources (build, hosting), so the charge stands.\n</Warning>\n\n## How to dispute or fix the issue\n\n<Steps>\n<Step title=\"Review the takedown notice\">\nCheck your email and workspace notifications for the specific policy violation cited. Many false positives stem from keywords in placeholder text, demo content, or authentication flows.\n</Step>\n\n<Step title=\"Submit a dispute (false positive)\">\nIf you believe your app was flagged in error, click **Dispute takedown** in the workspace banner or reply to the notification email. Include:\n\n- A brief description of the app's purpose\n- Why the flagged content is legitimate (e.g. \"auth form is for a real user login, not phishing\")\n\nOur support team reviews disputes within **24 hours** on business days. If approved, your app is restored to its original public URL.\n</Step>\n\n<Step title=\"Fix and re-publish (genuine violation)\">\nIf the takedown was correct - or if you prefer to fix the issue rather than wait for review - edit your app in the workspace:\n\n1. Ask the agent to remove or reword the problematic content\n2. Test the changes in preview\n3. Click **Re-publish** to publish a new version\n\nThe new published app will be re-screened automatically. If it passes, it goes live immediately.\n</Step>\n\n<Step title=\"Fork and replace (persistent issues)\">\nIf a specific workspace or app keeps triggering false positives, you can **fork** the project:\n\n1. Export your code (via **Github push** in the workspace)\n2. Start a new workspace and upload or describe the app again\n3. Publish from the clean slate\n\nThe new published app gets a fresh URL and a new screening pass.\n</Step>\n</Steps>\n\n## Preventing false positives\n\n<CardGroup cols={2}>\n<Card title=\"Avoid phishing keywords\" icon=\"shield-alert\">\nWords like \"verify your account,\" \"urgent action required,\" or fake login prompts trigger phishing filters. Use clear, honest language in forms and CTAs.\n</Card>\n\n<Card title=\"Label demo content clearly\" icon=\"tag\">\nIf your app includes placeholder or test data that resembles policy violations (e.g. fake reviews, mock scams for educational purposes), add visible labels like **\"Demo only\"** or **\"Example content\"**.\n</Card>\n\n<Card title=\"Use real branding sparingly\" icon=\"palette\">\nAvoid using trademarked logos, brand names, or UI that mimics well-known services unless you have permission or a clear parody/educational use case.\n</Card>\n\n<Card title=\"Review before publishing\" icon=\"eye\">\nPreview your app in the workspace before publishing. Look for anything a moderation system might misinterpret as malicious.\n</Card>\n</CardGroup>\n\n## Appeals and repeat offenders\n\n- **First takedown:** Dispute or fix freely; no penalty.\n- **Multiple violations:** Repeated policy breaches (especially after disputes are rejected) may result in account suspension or permanent bans.\n- **Malicious intent:** Apps designed to harm users, steal credentials, or violate laws result in immediate account termination with no refund.\n\n<Tip>\nEmergent's moderation is designed to be lenient for edge cases. If you're building something unconventional (satire, security research, etc.), reach out to support **before** publishing so we can whitelist or review it manually.\n</Tip>\n\n## Related topics\n\n<CardGroup cols={2}>\n<Card title=\"How apps work here\" icon=\"lightbulb\" href=\"/how-apps-work-here-mental-model\">\nUnderstand the published app and lifecycle of Emergent apps\n</Card>\n\n<Card title=\"How credits work\" icon=\"coins\" href=\"/managing-credit-usage\">\nWhy credits are consumed even if an app is taken down\n</Card>\n\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nPoint your own domain to a published app\n</Card>\n\n<Card title=\"Glossary\" icon=\"book-open\" href=\"/glossary-of-emergent-terms\">\nKey terms like \"workspace,\" \"published app,\" and \"fork\"\n</Card>\n</CardGroup>\n","order":101,"parent_id":null,"icon":"shield","description":"Deployed apps can be taken offline by automated content-policy/phishing screening; how to dispute and remedy via fork/replace.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-22T06:19:38.723669+00:00","published_at":"2026-09-22T06:19:38.723669+00:00","published_content":"## Why apps are sometimes taken down\n\nEmergent runs automated content-policy and phishing screening on all published apps to keep the platform safe and trustworthy for everyone. If an app triggers these filters - even by mistake - it may be automatically taken offline.\n\n<Callout type=\"info\" title=\"False positives happen\">\nAutomated moderation occasionally flags legitimate apps. We provide a simple dispute and recovery path so you're never permanently locked out of your work.\n</Callout>\n\nCommon triggers include:\n\n- Phishing keywords or suspicious login flows (e.g. credential harvesting forms)\n- Malicious content or content-policy violations (harassment, spam, illegal material)\n- Impersonation of well-known brands or services\n- Misleading or deceptive UI patterns\n\n## What happens when your app is flagged\n\n1. **Immediate takedown:** The live published app is removed from public access; the public URL returns a `403 Forbidden` or takedown notice.\n2. **Notification:** You receive an email and in-workspace alert explaining the reason for takedown.\n3. **Source code remains safe:** Your workspace, chat history, and code are **not deleted** - only the public published app is affected.\n\n<Warning>\nYour credits are **not** refunded for apps taken down after published app. The published app consumed platform resources (build, hosting), so the charge stands.\n</Warning>\n\n## How to dispute or fix the issue\n\n<Steps>\n<Step title=\"Review the takedown notice\">\nCheck your email and workspace notifications for the specific policy violation cited. Many false positives stem from keywords in placeholder text, demo content, or authentication flows.\n</Step>\n\n<Step title=\"Submit a dispute (false positive)\">\nIf you believe your app was flagged in error, click **Dispute takedown** in the workspace banner or reply to the notification email. Include:\n\n- A brief description of the app's purpose\n- Why the flagged content is legitimate (e.g. \"auth form is for a real user login, not phishing\")\n\nOur support team reviews disputes within **24 hours** on business days. If approved, your app is restored to its original public URL.\n</Step>\n\n<Step title=\"Fix and re-publish (genuine violation)\">\nIf the takedown was correct - or if you prefer to fix the issue rather than wait for review - edit your app in the workspace:\n\n1. Ask the agent to remove or reword the problematic content\n2. Test the changes in preview\n3. Click **Re-publish** to publish a new version\n\nThe new published app will be re-screened automatically. If it passes, it goes live immediately.\n</Step>\n\n<Step title=\"Fork and replace (persistent issues)\">\nIf a specific workspace or app keeps triggering false positives, you can **fork** the project:\n\n1. Export your code (via **Github push** in the workspace)\n2. Start a new workspace and upload or describe the app again\n3. Publish from the clean slate\n\nThe new published app gets a fresh URL and a new screening pass.\n</Step>\n</Steps>\n\n## Preventing false positives\n\n<CardGroup cols={2}>\n<Card title=\"Avoid phishing keywords\" icon=\"shield-alert\">\nWords like \"verify your account,\" \"urgent action required,\" or fake login prompts trigger phishing filters. Use clear, honest language in forms and CTAs.\n</Card>\n\n<Card title=\"Label demo content clearly\" icon=\"tag\">\nIf your app includes placeholder or test data that resembles policy violations (e.g. fake reviews, mock scams for educational purposes), add visible labels like **\"Demo only\"** or **\"Example content\"**.\n</Card>\n\n<Card title=\"Use real branding sparingly\" icon=\"palette\">\nAvoid using trademarked logos, brand names, or UI that mimics well-known services unless you have permission or a clear parody/educational use case.\n</Card>\n\n<Card title=\"Review before publishing\" icon=\"eye\">\nPreview your app in the workspace before publishing. Look for anything a moderation system might misinterpret as malicious.\n</Card>\n</CardGroup>\n\n## Appeals and repeat offenders\n\n- **First takedown:** Dispute or fix freely; no penalty.\n- **Multiple violations:** Repeated policy breaches (especially after disputes are rejected) may result in account suspension or permanent bans.\n- **Malicious intent:** Apps designed to harm users, steal credentials, or violate laws result in immediate account termination with no refund.\n\n<Tip>\nEmergent's moderation is designed to be lenient for edge cases. If you're building something unconventional (satire, security research, etc.), reach out to support **before** publishing so we can whitelist or review it manually.\n</Tip>\n\n## Related topics\n\n<CardGroup cols={2}>\n<Card title=\"How apps work here\" icon=\"lightbulb\" href=\"/how-apps-work-here-mental-model\">\nUnderstand the published app and lifecycle of Emergent apps\n</Card>\n\n<Card title=\"How credits work\" icon=\"coins\" href=\"/managing-credit-usage\">\nWhy credits are consumed even if an app is taken down\n</Card>\n\n<Card title=\"Custom domain\" icon=\"globe\" href=\"/custom-domain\">\nPoint your own domain to a published app\n</Card>\n\n<Card title=\"Glossary\" icon=\"book-open\" href=\"/glossary-of-emergent-terms\">\nKey terms like \"workspace,\" \"published app,\" and \"fork\"\n</Card>\n</CardGroup>\n","published_title":"App takedown & content moderation","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"e7b879ff-a85b-4237-8915-300964bce09c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"What is Wingman","slug":"what-is-wingman","content":"## Overview\n\n**Wingman** is Emergent's standalone personal AI assistant with persistent memory. It is a separate product from Emergent's app-building platform and is designed to help you with everyday tasks, questions, and conversations while remembering context across sessions.\n\nWingman is available on multiple platforms:\n\n- **Web** - [getwingman.com](https://getwingman.com)\n- **Android** - Google Play Store\n- **iOS** - Apple App Store\n\n<Note>\nWingman is **not** the AI that builds your apps inside Emergent. It is a personal assistant you can use for general productivity, brainstorming, research, and more.\n</Note>\n\n## Key features\n\n- **Phone calls** - Wingman can place outbound phone calls on your behalf; with an inline call card showing real-time status (dialing, in progress, completed).\n- **Persistent memory** - Wingman remembers your preferences, past conversations, and context over time; making interactions more personalized and efficient.\n- **Multi-platform sync** - Start a conversation on your phone and continue it on the web, with memory carried across devices.\n- **General-purpose assistant** - Ask questions, get summaries, draft content, or receive help with a wide range of everyday tasks.\n\n## How it differs from Emergent's app builder\n\n| Feature | Emergent App Builder | Wingman |\n|---------|---------------------|---------|\n| **Purpose** | Build, test and publish apps via chat | Personal AI assistant for general tasks |\n| **Memory** | Project-specific workspace context | Cross-conversation persistent memory |\n| **Access** | Emergent platform workspace | Standalone web app & mobile apps |\n| **Output** | Published web/mobile applications | Conversational assistance & answers |\n\n## Getting started\n\n<Steps>\n<Step title=\"Choose your platform\">\nVisit [getwingman.com](https://getwingman.com), or download the app from the Play Store (Android) or App Store (iOS).\n</Step>\n\n<Step title=\"Sign in\">\nCreate an account or sign in with your existing credentials. Your memory and conversation history will sync across all platforms where you're logged in.\n</Step>\n\n<Step title=\"Start chatting\">\nAsk Wingman anything - questions, tasks, ideas - and it will remember your preferences and context for future conversations.\n</Step>\n</Steps>\n\n<Tip>\nWingman's persistent memory means you don't need to re-explain your preferences or background every time you chat. The more you use it, the more tailored your experience becomes.\n</Tip>\n\n## Privacy & memory\n\nWingman's memory is designed to enhance your experience by retaining context. You remain in control:\n\n- Memory is tied to your account and syncs across your devices.\n- You can manage or clear stored memory at any time through the app settings.\n- Conversations and memory are not shared with other users or used to train Emergent's app-building models.\n\n<Info>\nFor questions about data handling and privacy, refer to Wingman's privacy policy available in-app and on the website.\n</Info>\n","order":102,"parent_id":null,"icon":"robot","description":"Emergent's standalone personal AI assistant with persistent memory - separate from the app builder; available on web (getwingman.com), the Play Store and the App Store.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-17T11:06:21.119969+00:00","published_at":"2026-09-17T11:06:21.119969+00:00","published_content":"## Overview\n\n**Wingman** is Emergent's standalone personal AI assistant with persistent memory. It is a separate product from Emergent's app-building platform and is designed to help you with everyday tasks, questions, and conversations while remembering context across sessions.\n\nWingman is available on multiple platforms:\n\n- **Web** - [getwingman.com](https://getwingman.com)\n- **Android** - Google Play Store\n- **iOS** - Apple App Store\n\n<Note>\nWingman is **not** the AI that builds your apps inside Emergent. It is a personal assistant you can use for general productivity, brainstorming, research, and more.\n</Note>\n\n## Key features\n\n- **Phone calls** - Wingman can place outbound phone calls on your behalf; with an inline call card showing real-time status (dialing, in progress, completed).\n- **Persistent memory** - Wingman remembers your preferences, past conversations, and context over time; making interactions more personalized and efficient.\n- **Multi-platform sync** - Start a conversation on your phone and continue it on the web, with memory carried across devices.\n- **General-purpose assistant** - Ask questions, get summaries, draft content, or receive help with a wide range of everyday tasks.\n\n## How it differs from Emergent's app builder\n\n| Feature | Emergent App Builder | Wingman |\n|---------|---------------------|---------|\n| **Purpose** | Build, test and publish apps via chat | Personal AI assistant for general tasks |\n| **Memory** | Project-specific workspace context | Cross-conversation persistent memory |\n| **Access** | Emergent platform workspace | Standalone web app & mobile apps |\n| **Output** | Published web/mobile applications | Conversational assistance & answers |\n\n## Getting started\n\n<Steps>\n<Step title=\"Choose your platform\">\nVisit [getwingman.com](https://getwingman.com), or download the app from the Play Store (Android) or App Store (iOS).\n</Step>\n\n<Step title=\"Sign in\">\nCreate an account or sign in with your existing credentials. Your memory and conversation history will sync across all platforms where you're logged in.\n</Step>\n\n<Step title=\"Start chatting\">\nAsk Wingman anything - questions, tasks, ideas - and it will remember your preferences and context for future conversations.\n</Step>\n</Steps>\n\n<Tip>\nWingman's persistent memory means you don't need to re-explain your preferences or background every time you chat. The more you use it, the more tailored your experience becomes.\n</Tip>\n\n## Privacy & memory\n\nWingman's memory is designed to enhance your experience by retaining context. You remain in control:\n\n- Memory is tied to your account and syncs across your devices.\n- You can manage or clear stored memory at any time through the app settings.\n- Conversations and memory are not shared with other users or used to train Emergent's app-building models.\n\n<Info>\nFor questions about data handling and privacy, refer to Wingman's privacy policy available in-app and on the website.\n</Info>\n","published_title":"What is Wingman","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"96765aec-dcbe-4132-958e-3a70fb75575c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Channels (Web, Telegram, WhatsApp)","slug":"channels-web-telegram-whatsapp-imessage-slack","content":"## Overview\n\nWingman works smoothly across **Web, Telegram, and WhatsApp**. Each channel supports text, voice messages, and images. You can also accept payments directly in-channel.\n\nAll channels share the same Wingman backend - conversations sync across platforms when users link their accounts.\n\n---\n\n## Supported Channels\n\n<CardGroup cols={2}>\n <Card title=\"Web\" icon=\"globe\">\n Toggle to Wingman on the Emergent website and start chatting\n </Card>\n <Card title=\"Telegram\" icon=\"send\">\n Connect a Telegram account by scanning a QR code.\n </Card>\n <Card title=\"WhatsApp\" icon=\"message-circle\">\n Connect a WhatsApp account by scanning a QR code.\n </Card>\n</CardGroup>\n\n---\n\n## Message and Voice Limits\n\nEach channel enforces different size and duration caps:\n\n| Channel | Text message max | Voice message max | Image max |\n|------------|------------------|-------------------|-----------|\n| Web | 10,000 chars | 10 MB / 2 min | 10 MB |\n| Telegram | 4,096 chars | 10 MB / 2 min | 10 MB |\n| WhatsApp | 4,096 chars | 10 MB / 2 min | 5 MB |\n\n<Note>\nVoice messages are automatically transcribed and processed; the 10 MB / 2 min limit applies to the uploaded audio file.\n</Note>\n\n---\n\n## Connecting a Channel\n\n<Steps>\n <Step title=\"Select your channel\">\n In the Wingman workspace, go to **Setup → Channels** and choose which platform to connect.\n </Step>\n\n <Step title=\"Follow the platform-specific flow\">\n - **Web**: Nothing to set up - your Wingman is available on the web automatically.\n - **Telegram**: Scan the QR code to connect your Telegram account.\n - **WhatsApp**: Scan the QR code and you're good to go.\n </Step>\n\n <Step title=\"Test the connection\">\n Send a test message from the channel; you should see it appear in the Wingman **Inbox** within seconds.\n </Step>\n</Steps>\n\n<Tip>\nRan out of credits while chatting with Wingman. Recharge directly from Whatsapp or Telegram. \n</Tip>\n\n---\n\n## Channel-Specific Considerations\n\n### Telegram\n- Connect by scanning the QR code in **Setup → Channels**.\n- Rich media: stickers, polls, and inline keyboards work natively.\n\n### WhatsApp\n- Connect by scanning the QR code - no extra setup required.\n\n### Web\n- Fully customizable widget appearance (colors, avatar, placement).\n- No platform approval needed - deploy instantly.\n\n---\n\n## Syncing Conversations Across Channels\n\nWhen a user links their Telegram, WhatsApp, and Web accounts (via email or phone number), Wingman **unifies the conversation history**:\n\n1. User chats on Telegram, then continues on Web.\n2. Wingman recognizes the same user and retrieves context.\n3. The **Inbox** shows a single threaded conversation across all channels.\n\n<Note>\nAccount linking is optional but recommended for a smooth experience. Users initiate linking by verifying their contact details in any channel.\n</Note>\n","order":103,"parent_id":null,"icon":"mail","description":"Use Wingman across messaging channels; per-channel message/voice limits (voice up to 10MB / 2min), connection flows, in-channel payments, the WhatsApp 24-hour window, and per-chann","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-10T13:20:58.965523+00:00","published_at":"2026-09-10T13:20:58.965523+00:00","published_content":"## Overview\n\nWingman works smoothly across **Web, Telegram, and WhatsApp**. Each channel supports text, voice messages, and images. You can also accept payments directly in-channel.\n\nAll channels share the same Wingman backend - conversations sync across platforms when users link their accounts.\n\n---\n\n## Supported Channels\n\n<CardGroup cols={2}>\n <Card title=\"Web\" icon=\"globe\">\n Toggle to Wingman on the Emergent website and start chatting\n </Card>\n <Card title=\"Telegram\" icon=\"send\">\n Connect a Telegram account by scanning a QR code.\n </Card>\n <Card title=\"WhatsApp\" icon=\"message-circle\">\n Connect a WhatsApp account by scanning a QR code.\n </Card>\n</CardGroup>\n\n---\n\n## Message and Voice Limits\n\nEach channel enforces different size and duration caps:\n\n| Channel | Text message max | Voice message max | Image max |\n|------------|------------------|-------------------|-----------|\n| Web | 10,000 chars | 10 MB / 2 min | 10 MB |\n| Telegram | 4,096 chars | 10 MB / 2 min | 10 MB |\n| WhatsApp | 4,096 chars | 10 MB / 2 min | 5 MB |\n\n<Note>\nVoice messages are automatically transcribed and processed; the 10 MB / 2 min limit applies to the uploaded audio file.\n</Note>\n\n---\n\n## Connecting a Channel\n\n<Steps>\n <Step title=\"Select your channel\">\n In the Wingman workspace, go to **Setup → Channels** and choose which platform to connect.\n </Step>\n\n <Step title=\"Follow the platform-specific flow\">\n - **Web**: Nothing to set up - your Wingman is available on the web automatically.\n - **Telegram**: Scan the QR code to connect your Telegram account.\n - **WhatsApp**: Scan the QR code and you're good to go.\n </Step>\n\n <Step title=\"Test the connection\">\n Send a test message from the channel; you should see it appear in the Wingman **Inbox** within seconds.\n </Step>\n</Steps>\n\n<Tip>\nRan out of credits while chatting with Wingman. Recharge directly from Whatsapp or Telegram. \n</Tip>\n\n---\n\n## Channel-Specific Considerations\n\n### Telegram\n- Connect by scanning the QR code in **Setup → Channels**.\n- Rich media: stickers, polls, and inline keyboards work natively.\n\n### WhatsApp\n- Connect by scanning the QR code - no extra setup required.\n\n### Web\n- Fully customizable widget appearance (colors, avatar, placement).\n- No platform approval needed - deploy instantly.\n\n---\n\n## Syncing Conversations Across Channels\n\nWhen a user links their Telegram, WhatsApp, and Web accounts (via email or phone number), Wingman **unifies the conversation history**:\n\n1. User chats on Telegram, then continues on Web.\n2. Wingman recognizes the same user and retrieves context.\n3. The **Inbox** shows a single threaded conversation across all channels.\n\n<Note>\nAccount linking is optional but recommended for a smooth experience. Users initiate linking by verifying their contact details in any channel.\n</Note>\n","published_title":"Channels (Web, Telegram, WhatsApp)","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"064736ca-bb34-4fe8-9d76-d1873f20dda8","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Wingman Integrations & Tasks","slug":"integrations-scheduled-tasks","content":"Your Wingman can connect to **300+ external services** (Gmail, LinkedIn, Notion, Slack, and more) to take actions on your behalf, and run **scheduled tasks**, recurring automations or one-time jobs that execute even when you're not chatting.\nTo add these integrations and tasks, you can directly ask your wingman.\n\n## Built-in Capabilities\n\nYour Wingman has several capabilities that work **without connecting any integration**:\n\n- **Web search** - searches the internet for current information, articles, and data\n- **File analysis** - directly reads PNG, JPEG, GIF, WebP, and PDF files. For other formats like Excel, CSV, or other spreadsheets, your Wingman uses code execution to parse and analyze them.\n- **Code execution** - can write and run code to process data, generate files, and automate tasks\n- **Memory** - remembers facts and preferences across conversations\n\nIntegrations extend these capabilities by giving your Wingman access to your personal accounts and services.\n\n## Integrations\n\n### What Integrations Do\n\nIntegrations give your Wingman **OAuth or API access** to external services. Once connected, your Wingman can search for available actions, read data, and perform operations in that service, like fetching your Gmail inbox, creating a LinkedIn post, or adding a row to a Google Sheet.\n\nEach Wingman has its own separate connections. Connecting Gmail to one Wingman does not give your other Wingmen access to Gmail.\n\n### Available Integrations\n\n| Category | Services |\n| --- | --- |\n| **Google** | Gmail, Google Calendar, Google Sheets, Google Drive, Google Docs, Google Slides, Google Meet |\n| **Productivity** | Notion, Asana, Trello, Linear, Airtable, Monday.com, Jira |\n| **Communication** | Slack, Discord, Outlook, Mailchimp, SendGrid |\n| **Social** | LinkedIn, X (Twitter), Instagram, Facebook |\n| **CRM & Sales** | HubSpot, Salesforce, Pipedrive, Calendly |\n| **Support** | Freshdesk, Zendesk, Intercom |\n| **Finance** | Stripe, Shopify, QuickBooks, Xero |\n| **Developer** | GitHub, Supabase, Figma |\n| **Other** | Zoom, Dropbox, Make, Typeform, DocuSign |\n\n### Connecting an Integration\n\n1. Click **Setup** (top-right) → **Integrations**.\n2. Search or browse the grid of available services.\n3. Click the **connect icon** on the service you want.\n4. A new window opens with the service's OAuth consent screen. You'll see **\"Composio would like to:\"** followed by the permissions being requested, this is expected. Composio is the integration infrastructure that manages OAuth connections on behalf of Emergent.\n5. Click **Allow**.\n6. A success page appears: **\"[Service] Connected, You can close this window and return to your conversation.\"** The page auto-closes in 2 seconds.\n\nConnected integrations show a green **\"active\"** badge in the Integrations grid. Click the **three-dot menu** (⋯) to disconnect.\n\n### What Your Wingman Can Do With Integrations\n\nCapabilities vary by service. Your Wingman automatically discovers what actions are available for each connected integration. For example:\n\n- **Gmail** - read, search, send, and draft emails\n- **Google Calendar** - view, create, and manage events\n- **LinkedIn** - create and delete posts, fetch profile information (connection request management is not currently supported)\n- **Notion** - read and write pages and databases\n- **GitHub** - manage repositories, issues, and pull requests\n\nWhen your Wingman doesn't have a direct integration action for something, it tries alternative approaches, for example, checking your Gmail for LinkedIn notification emails, or using web search to find information.\n\n### Accessing Apps Built on Emergent\n\nIf you have applications built on the Emergent app builder, your Wingman can access their databases directly, no separate integration setup required. This is native to the platform.\n\n### Integration Permissions\n\nRead-only actions (searching, fetching data) are performed automatically. Actions that modify external data (sending an email, creating a post, deleting a record) require your **explicit approval** before execution. You can grant one-time approval or \"Always Allow\" for a specific action type. See **Wingman Channels** for how approval prompts appear on each channel.\n\n---\n\n## Scheduled Tasks\n\n### What Tasks Are\n\nTasks are automated jobs your Wingman runs on a schedule, even when you're not chatting. A task can be **recurring** (runs on a cron schedule, for e.g., every weekday at 9am) or **one-time** (runs once at a specific date and time).\n\n### Creating a Task\n\nOpen the **Tasks** tab (next to Chat at the top of the Wingman interface). When empty, it shows suggested templates:\n\n- \"Send me a daily email summary\"\n- \"Remind me every Monday at 9am\"\n- \"Check my calendar every morning\"\n- \"Weekly project status report\"\n\nClick a suggestion to get started, or describe a custom task in the chat. Your Wingman creates the schedule and confirms the details.\n\nYou can also just ask your wingman to create a scheduled task conversationally.\n\n### How Tasks Execute\n\nWhen a scheduled task fires, your Wingman receives the full context - your identity, personality, connected integrations, and channel presence. It executes the task and delivers the result to the **delivery channel** you specified (web, Telegram, WhatsApp). Scheduled tasks run independently and continue working even when you're not chatting.\n\nAll schedules are **timezone-aware**, \"every day at 9am\" means 9am in your timezone.\n\n### Managing Tasks\n\nFrom the **Tasks** tab, you can:\n\n- **Pause** a task: temporarily stops it from executing\n- **Resume** a paused task\n- **Edit**: change the schedule, task description, or delivery channel\n- **Delete**: permanently remove the task\n\nYou can also manage tasks conversationally by telling your Wingman in chat (for e.g., \"pause my daily email summary\" or \"change my Monday reminder to 10am\").\n\n### Paused Tasks & Auto-Resume\n\nIf a scheduled task fails because your account has **insufficient credits**, the task is automatically paused with a status of **Paused (No Credits)**. Once you add more credits to your account, paused tasks **automatically resume**, no manual action is required. Your Wingman receives a signal when credits are available again and restarts any tasks that were paused for this reason.\n\n## Deleting a Wingman\n\nDisconnecting a single channel (the **Disconnect** action on Telegram/WhatsApp in the **Channels** section) leaves the Wingman itself intact. To delete a Wingman **entirely**, not just unhook one channel:\n\n1. Click **Setup** (top-right of the Wingman interface: on **app.emergent.sh/wingman**, **getwingman.com**).\n2. Go to the **Settings** section.\n3. Scroll to the bottom and click **Delete Wingman [Name]**.\n4. Confirm by clicking the red **Delete [Name]** button.\n\nThis is **permanent** and wipes everything tied to that Wingman: all conversations, connected integrations, channels, and scheduled automations.\n\n## Related\n\n- **What is Wingman** - overview and getting started\n- **Wingman Channels** - connecting Telegram, WhatsApp\n- **How Credits Work** - credit types, costs, billing\n","order":104,"parent_id":null,"icon":"clock","description":"300+ OAuth integrations per Wingman (via Composio), built-in capabilities (web search, file analysis, code execution, memory), and recurring/one-time scheduled tasks with delivery ","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-17T11:06:21.124050+00:00","published_at":"2026-09-17T11:06:21.124050+00:00","published_content":"Your Wingman can connect to **300+ external services** (Gmail, LinkedIn, Notion, Slack, and more) to take actions on your behalf, and run **scheduled tasks**, recurring automations or one-time jobs that execute even when you're not chatting.\nTo add these integrations and tasks, you can directly ask your wingman.\n\n## Built-in Capabilities\n\nYour Wingman has several capabilities that work **without connecting any integration**:\n\n- **Web search** - searches the internet for current information, articles, and data\n- **File analysis** - directly reads PNG, JPEG, GIF, WebP, and PDF files. For other formats like Excel, CSV, or other spreadsheets, your Wingman uses code execution to parse and analyze them.\n- **Code execution** - can write and run code to process data, generate files, and automate tasks\n- **Memory** - remembers facts and preferences across conversations\n\nIntegrations extend these capabilities by giving your Wingman access to your personal accounts and services.\n\n## Integrations\n\n### What Integrations Do\n\nIntegrations give your Wingman **OAuth or API access** to external services. Once connected, your Wingman can search for available actions, read data, and perform operations in that service, like fetching your Gmail inbox, creating a LinkedIn post, or adding a row to a Google Sheet.\n\nEach Wingman has its own separate connections. Connecting Gmail to one Wingman does not give your other Wingmen access to Gmail.\n\n### Available Integrations\n\n| Category | Services |\n| --- | --- |\n| **Google** | Gmail, Google Calendar, Google Sheets, Google Drive, Google Docs, Google Slides, Google Meet |\n| **Productivity** | Notion, Asana, Trello, Linear, Airtable, Monday.com, Jira |\n| **Communication** | Slack, Discord, Outlook, Mailchimp, SendGrid |\n| **Social** | LinkedIn, X (Twitter), Instagram, Facebook |\n| **CRM & Sales** | HubSpot, Salesforce, Pipedrive, Calendly |\n| **Support** | Freshdesk, Zendesk, Intercom |\n| **Finance** | Stripe, Shopify, QuickBooks, Xero |\n| **Developer** | GitHub, Supabase, Figma |\n| **Other** | Zoom, Dropbox, Make, Typeform, DocuSign |\n\n### Connecting an Integration\n\n1. Click **Setup** (top-right) → **Integrations**.\n2. Search or browse the grid of available services.\n3. Click the **connect icon** on the service you want.\n4. A new window opens with the service's OAuth consent screen. You'll see **\"Composio would like to:\"** followed by the permissions being requested, this is expected. Composio is the integration infrastructure that manages OAuth connections on behalf of Emergent.\n5. Click **Allow**.\n6. A success page appears: **\"[Service] Connected, You can close this window and return to your conversation.\"** The page auto-closes in 2 seconds.\n\nConnected integrations show a green **\"active\"** badge in the Integrations grid. Click the **three-dot menu** (⋯) to disconnect.\n\n### What Your Wingman Can Do With Integrations\n\nCapabilities vary by service. Your Wingman automatically discovers what actions are available for each connected integration. For example:\n\n- **Gmail** - read, search, send, and draft emails\n- **Google Calendar** - view, create, and manage events\n- **LinkedIn** - create and delete posts, fetch profile information (connection request management is not currently supported)\n- **Notion** - read and write pages and databases\n- **GitHub** - manage repositories, issues, and pull requests\n\nWhen your Wingman doesn't have a direct integration action for something, it tries alternative approaches, for example, checking your Gmail for LinkedIn notification emails, or using web search to find information.\n\n### Accessing Apps Built on Emergent\n\nIf you have applications built on the Emergent app builder, your Wingman can access their databases directly, no separate integration setup required. This is native to the platform.\n\n### Integration Permissions\n\nRead-only actions (searching, fetching data) are performed automatically. Actions that modify external data (sending an email, creating a post, deleting a record) require your **explicit approval** before execution. You can grant one-time approval or \"Always Allow\" for a specific action type. See **Wingman Channels** for how approval prompts appear on each channel.\n\n---\n\n## Scheduled Tasks\n\n### What Tasks Are\n\nTasks are automated jobs your Wingman runs on a schedule, even when you're not chatting. A task can be **recurring** (runs on a cron schedule, for e.g., every weekday at 9am) or **one-time** (runs once at a specific date and time).\n\n### Creating a Task\n\nOpen the **Tasks** tab (next to Chat at the top of the Wingman interface). When empty, it shows suggested templates:\n\n- \"Send me a daily email summary\"\n- \"Remind me every Monday at 9am\"\n- \"Check my calendar every morning\"\n- \"Weekly project status report\"\n\nClick a suggestion to get started, or describe a custom task in the chat. Your Wingman creates the schedule and confirms the details.\n\nYou can also just ask your wingman to create a scheduled task conversationally.\n\n### How Tasks Execute\n\nWhen a scheduled task fires, your Wingman receives the full context - your identity, personality, connected integrations, and channel presence. It executes the task and delivers the result to the **delivery channel** you specified (web, Telegram, WhatsApp). Scheduled tasks run independently and continue working even when you're not chatting.\n\nAll schedules are **timezone-aware**, \"every day at 9am\" means 9am in your timezone.\n\n### Managing Tasks\n\nFrom the **Tasks** tab, you can:\n\n- **Pause** a task: temporarily stops it from executing\n- **Resume** a paused task\n- **Edit**: change the schedule, task description, or delivery channel\n- **Delete**: permanently remove the task\n\nYou can also manage tasks conversationally by telling your Wingman in chat (for e.g., \"pause my daily email summary\" or \"change my Monday reminder to 10am\").\n\n### Paused Tasks & Auto-Resume\n\nIf a scheduled task fails because your account has **insufficient credits**, the task is automatically paused with a status of **Paused (No Credits)**. Once you add more credits to your account, paused tasks **automatically resume**, no manual action is required. Your Wingman receives a signal when credits are available again and restarts any tasks that were paused for this reason.\n\n## Deleting a Wingman\n\nDisconnecting a single channel (the **Disconnect** action on Telegram/WhatsApp in the **Channels** section) leaves the Wingman itself intact. To delete a Wingman **entirely**, not just unhook one channel:\n\n1. Click **Setup** (top-right of the Wingman interface: on **app.emergent.sh/wingman**, **getwingman.com**).\n2. Go to the **Settings** section.\n3. Scroll to the bottom and click **Delete Wingman [Name]**.\n4. Confirm by clicking the red **Delete [Name]** button.\n\nThis is **permanent** and wipes everything tied to that Wingman: all conversations, connected integrations, channels, and scheduled automations.\n\n## Related\n\n- **What is Wingman** - overview and getting started\n- **Wingman Channels** - connecting Telegram, WhatsApp\n- **How Credits Work** - credit types, costs, billing\n","published_title":"Wingman Integrations & Tasks","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null,"deleted_at":null,"deleted_by":null,"deleted_by_name":null,"trash_nav":null},{"id":"6b534259-64bc-4d15-89cb-2ca752eb75d1","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Custom & MCP Integrations for Wingman","slug":"custom-mcp-integrations","content":"Beyond the built-in OAuth integrations (see **Wingman Integrations & Tasks**), Wingman can also connect to tools through **APIs** and **MCP (Model Context Protocol)**, an open standard that apps expose so AI agents can access their data and take actions. MCP lets you connect Wingman to more tools without waiting for a custom-built integration for every app. You can add these integrations and mcp by asking your wingman directly.\n\nYou don't need to think about the underlying technology: MCP-backed tools appear inside the same **Integrations** surface as everything else. There are two kinds.\n\n## Wingman-Managed (First-Party) MCP Integrations\n\nThese are MCP integrations added and maintained by the Wingman team. They behave like any other integration:\n\n1. Open **Integrations** and find the integration by browsing or searching.\n2. Start the standard **connect** flow.\n3. Wingman handles authentication using the same patterns as other integrations.\n4. Once connected, the integration's tools become available to your Wingman.\n5. Manage, disconnect, or reconnect it from the same Integrations surface.\n\nYou can also just ask your Wingman in chat to do something that needs one of these integrations - it will identify the right integration and walk you through connecting it, then continue your task.\n\n## Custom (Third-Party) MCP Servers\n\nYou can also add your own MCP server, for example, one provided by a tool you already use.\n\n### Adding a custom MCP server\n\n1. Ask your wingman to connect with a custom MCP server.\n2. Provide either:\n   - the MCP server's **endpoint URL**, or\n   - a **JSON config** using the standard `mcpServers` shape used by MCP clients (e.g., Claude Code / Desktop).\n3. Wingman validates that the server supports **hosted HTTP MCP** and reads its metadata to suggest a display name (you can rename it).\n4. If the server needs authentication, Wingman prompts you through a **secure credential flow** (bearer token, API key, or custom header), you never paste secrets into the chat. Only references to those secrets are stored, not the raw values.\n5. Wingman discovers the server's available tools and registers the ones you enable for that Wingman.\n6. View status, disconnect, or remove the custom integration anytime from **Integrations**.\n\n### Permissions\n\nMCP tools use the **same permission flow** as the rest of your Wingman's tools: read-only actions run automatically, while actions that modify data ask for your approval before running. See **Wingman Channels** for how approval prompts appear on each channel.\n\n## Supported & Not Yet Supported\n\n- **Supported:** hosted **HTTP / Streamable HTTP** MCP servers (servers already running at a URL). Wingman only needs the endpoint and auth details to validate the server, discover tools, and call them.\n- **Not yet supported:** **command-based / local MCP servers** (e.g., `npx`, `uvx`, stdio). These require running a local process and are planned for a later phase.\n\nRemoving a custom MCP integration revokes its credentials, removes its tools, clears cached schemas, and invalidates any permissions tied to that server.\n\n## Related\n\n- **Wingman Integrations & Tasks** - OAuth integrations and scheduled tasks\n- **Wingman Channels** - connecting Telegram, WhatsApp\n- **What is Wingman** - overview and getting started\n","order":105,"parent_id":null,"icon":"puzzle","description":"Add first-party and custom third-party MCP servers to Wingman via endpoint/JSON config; credential handling and supported vs unsupported server types.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-17T11:06:21.120691+00:00","published_at":"2026-09-17T11:06:21.120691+00:00","published_content":"Beyond the built-in OAuth integrations (see **Wingman Integrations & Tasks**), Wingman can also connect to tools through **APIs** and **MCP (Model Context Protocol)**, an open standard that apps expose so AI agents can access their data and take actions. MCP lets you connect Wingman to more tools without waiting for a custom-built integration for every app. You can add these integrations and mcp by asking your wingman directly.\n\nYou don't need to think about the underlying technology: MCP-backed tools appear inside the same **Integrations** surface as everything else. There are two kinds.\n\n## Wingman-Managed (First-Party) MCP Integrations\n\nThese are MCP integrations added and maintained by the Wingman team. They behave like any other integration:\n\n1. Open **Integrations** and find the integration by browsing or searching.\n2. Start the standard **connect** flow.\n3. Wingman handles authentication using the same patterns as other integrations.\n4. Once connected, the integration's tools become available to your Wingman.\n5. Manage, disconnect, or reconnect it from the same Integrations surface.\n\nYou can also just ask your Wingman in chat to do something that needs one of these integrations - it will identify the right integration and walk you through connecting it, then continue your task.\n\n## Custom (Third-Party) MCP Servers\n\nYou can also add your own MCP server, for example, one provided by a tool you already use.\n\n### Adding a custom MCP server\n\n1. Ask your wingman to connect with a custom MCP server.\n2. Provide either:\n   - the MCP server's **endpoint URL**, or\n   - a **JSON config** using the standard `mcpServers` shape used by MCP clients (e.g., Claude Code / Desktop).\n3. Wingman validates that the server supports **hosted HTTP MCP** and reads its metadata to suggest a display name (you can rename it).\n4. If the server needs authentication, Wingman prompts you through a **secure credential flow** (bearer token, API key, or custom header), you never paste secrets into the chat. Only references to those secrets are stored, not the raw values.\n5. Wingman discovers the server's available tools and registers the ones you enable for that Wingman.\n6. View status, disconnect, or remove the custom integration anytime from **Integrations**.\n\n### Permissions\n\nMCP tools use the **same permission flow** as the rest of your Wingman's tools: read-only actions run automatically, while actions that modify data ask for your approval before running. See **Wingman Channels** for how approval prompts appear on each channel.\n\n## Supported & Not Yet Supported\n\n- **Supported:** hosted **HTTP / Streamable HTTP** MCP servers (servers already running at a URL). Wingman only needs the endpoint and auth details to validate the server, discover tools, and call them.\n- **Not yet supported:** **command-based / local MCP servers** (e.g., `npx`, `uvx`, stdio). These require running a local process and are planned for a later phase.\n\nRemoving a custom MCP integration revokes its credentials, removes its tools, clears cached schemas, and invalidates any permissions tied to that server.\n\n## Related\n\n- **Wingman Integrations & Tasks** - OAuth integrations and scheduled tasks\n- **Wingman Channels** - connecting Telegram, WhatsApp\n- **What is Wingman** - overview and getting started\n","published_title":"Custom & MCP Integrations for Wingman","status":"published","deleted_at":null,"reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"169fef15-3ca3-48d7-b407-e61ae8abaf28","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Start with your idea","slug":"start-with-your-idea","content":"Type what you want in one sentence and let the agent figure out the details - you don't need technical language or perfect specs to get started.\n\n---\n\n## Words you'll see on Emergent\n\nFour words come up on every page after this one, here's what they mean:\n\n- **Job**: one app or task, with its own chat, code, and preview. Everything you build lives inside a job. **Preview**: your private working copy of the app, updated live as the agent builds. It's not your published site, but you can share its link with teammates for feedback (it sleeps after about 30 minutes of inactivity).\n- **Publish**: the button that takes your app live on the internet, at its own permanent address. (**Re-publish** pushes later updates.)\n- **Credits**: what powers everything: the agent's work bills per usage, and keeping an app live has a monthly fee. Full picture in [How credits work](/how-credits-work-basics).\n\n---\n\n## Where you start\n\nOn the home screen, pick an **app type**, **Full Stack App**, **Mobile App**, **Landing Page**, or **Brainstorm**, then type your prompt in the composer. (The composer also has a **Build / Plan** switcher, more on that in [Talk it through first](/talk-it-through).) The app type is fixed for that job, so if you're unsure which fits, ask in a Brainstorm first or see [Talk it through first](/talk-it-through).\n\n---\n\n## Anatomy of a first prompt\n\nA good first prompt has three ingredients:\n\n1. **What** - the core purpose in one sentence (\"a book tracker,\" \"a habit logger,\" \"a quick notes app\")\n2. **Who** - who uses it (just you, a team, customers)\n3. **One core action** - the main thing people do (\"add books and mark them read,\" \"check off daily habits,\" \"save notes with tags\")\n\nYou can add more - design preferences, a list of fields, how it should feel to use - but those three pieces are enough to start.\n\n<Callout type=\"tip\" title=\"Keep it simple\">\nThe simpler your first idea, the faster you'll see results and understand how the platform thinks.\n\n</Callout>\n\n---\n\n## Example prompts\n\n**Book tracker:**\n\n```\nBuild a book tracker app where I can:\n- Add books with title, author, cover image URL, and rating\n- Mark books as read or unread\n- Filter by read status\n- Search by title or author\n\nDesign: Clean and minimal, good use of whitespace.\nHow it should feel: Fast to add a new book - prefer a floating action button and inline form.\n```\n\n**Habit tracker:**\n\n```\nBuild a habit tracker where I can:\n- Add habits with a name and daily checkbox\n- Mark each habit complete for today\n- See a streak count for each habit\n\nDesign: Warm and colorful.\nHow it should feel: One-tap to check off a habit.\n```\n\n**Expense logger:**\n\n```\nBuild a simple expense logger where I can:\n- Add expenses with amount, category, and date\n- Filter by category\n- See total spent this month\n\nDesign: Modern, dark mode preferred.\nHow it should feel: Fast data entry - prefer inline form at top of list.\n```\n\nEach of these prompts produces a working app with a database, a look and feel, and a preview URL. Publishing to a live URL requires a paid Publish (minimum 50 credits), see [Publish your app](/put-your-app-live).\n\n---\n\n## What NOT to worry about\n\nWhen you're starting out, skip these details - the agent handles them for you:\n\n- **Tech stack** - the agent picks the tools for you (React, MongoDB and more) automatically\n- **Database structure** - field types, indexes, and relationships are inferred from your description\n- **File structure** - components, routes, and connections to other services are organized for you\n- **Design polish** - you can refine colors, spacing, and layout after the first version is built\n\nFocus on *what* the app does and *how* it should feel. The agent translates that into working code.\n\n<Callout type=\"note\" title=\"You can always iterate\">\nAfter the first build, describe changes in chat and the agent updates the app. Design tweaks, new features, and bug fixes happen the same way - just ask.\n\n</Callout>\n\n---\n\n## Fill-in-the-blank template\n\nCopy this template and fill in the blanks to write your first prompt:\n\n```\nBuild a [type of app] where I can:\n- [core action 1]\n- [core action 2]\n- [core action 3]\n\nDesign: [visual style or mood]\nHow it should feel: [how it should feel to use]\n```\n\n**Example:**\n\n```\nBuild a recipe organizer where I can:\n- Add recipes with title, ingredients, and instructions\n- Tag recipes by cuisine or meal type\n- Search by ingredient or tag\n\nDesign: Clean and modern\nHow it should feel: Easy to scan and quick to add new recipes\n```\n\nPaste your prompt into the composer and send it, in **Build** mode the agent starts working right away.\n\nYou'll see a working app in under 20 minutes.\n\n---\n\n## If something looks wrong\n\nAfter the first build, test the app in the preview pane. If a feature is missing or broken, describe the issue in chat - the agent will fix it. When you're ready to take it live, see [Publish your app](/put-your-app-live).\n\nFor more on the full workflow, see the next article in this path.\n\n**Go deeper:** [What kind of apps you can build?](/what-kind-of-apps-you-can-build) · [What is a Job?](/what-is-a-job)\n","order":106,"parent_id":null,"icon":"lightbulb","description":"Describe what you want in one sentence - plain English is enough.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-10-05T14:07:33.096944+00:00","published_at":"2026-10-05T14:07:33.096944+00:00","published_content":"Type what you want in one sentence and let the agent figure out the details - you don't need technical language or perfect specs to get started.\n\n---\n\n## Words you'll see on Emergent\n\nFour words come up on every page after this one, here's what they mean:\n\n- **Job**: one app or task, with its own chat, code, and preview. Everything you build lives inside a job. **Preview**: your private working copy of the app, updated live as the agent builds. It's not your published site, but you can share its link with teammates for feedback (it sleeps after about 30 minutes of inactivity).\n- **Publish**: the button that takes your app live on the internet, at its own permanent address. (**Re-publish** pushes later updates.)\n- **Credits**: what powers everything: the agent's work bills per usage, and keeping an app live has a monthly fee. Full picture in [How credits work](/how-credits-work-basics).\n\n---\n\n## Where you start\n\nOn the home screen, pick an **app type**, **Full Stack App**, **Mobile App**, **Landing Page**, or **Brainstorm**, then type your prompt in the composer. (The composer also has a **Build / Plan** switcher, more on that in [Talk it through first](/talk-it-through).) The app type is fixed for that job, so if you're unsure which fits, ask in a Brainstorm first or see [Talk it through first](/talk-it-through).\n\n---\n\n## Anatomy of a first prompt\n\nA good first prompt has three ingredients:\n\n1. **What** - the core purpose in one sentence (\"a book tracker,\" \"a habit logger,\" \"a quick notes app\")\n2. **Who** - who uses it (just you, a team, customers)\n3. **One core action** - the main thing people do (\"add books and mark them read,\" \"check off daily habits,\" \"save notes with tags\")\n\nYou can add more - design preferences, a list of fields, how it should feel to use - but those three pieces are enough to start.\n\n<Callout type=\"tip\" title=\"Keep it simple\">\nThe simpler your first idea, the faster you'll see results and understand how the platform thinks.\n\n</Callout>\n\n---\n\n## Example prompts\n\n**Book tracker:**\n\n```\nBuild a book tracker app where I can:\n- Add books with title, author, cover image URL, and rating\n- Mark books as read or unread\n- Filter by read status\n- Search by title or author\n\nDesign: Clean and minimal, good use of whitespace.\nHow it should feel: Fast to add a new book - prefer a floating action button and inline form.\n```\n\n**Habit tracker:**\n\n```\nBuild a habit tracker where I can:\n- Add habits with a name and daily checkbox\n- Mark each habit complete for today\n- See a streak count for each habit\n\nDesign: Warm and colorful.\nHow it should feel: One-tap to check off a habit.\n```\n\n**Expense logger:**\n\n```\nBuild a simple expense logger where I can:\n- Add expenses with amount, category, and date\n- Filter by category\n- See total spent this month\n\nDesign: Modern, dark mode preferred.\nHow it should feel: Fast data entry - prefer inline form at top of list.\n```\n\nEach of these prompts produces a working app with a database, a look and feel, and a preview URL. Publishing to a live URL requires a paid Publish (minimum 50 credits), see [Publish your app](/put-your-app-live).\n\n---\n\n## What NOT to worry about\n\nWhen you're starting out, skip these details - the agent handles them for you:\n\n- **Tech stack** - the agent picks the tools for you (React, MongoDB and more) automatically\n- **Database structure** - field types, indexes, and relationships are inferred from your description\n- **File structure** - components, routes, and connections to other services are organized for you\n- **Design polish** - you can refine colors, spacing, and layout after the first version is built\n\nFocus on *what* the app does and *how* it should feel. The agent translates that into working code.\n\n<Callout type=\"note\" title=\"You can always iterate\">\nAfter the first build, describe changes in chat and the agent updates the app. Design tweaks, new features, and bug fixes happen the same way - just ask.\n\n</Callout>\n\n---\n\n## Fill-in-the-blank template\n\nCopy this template and fill in the blanks to write your first prompt:\n\n```\nBuild a [type of app] where I can:\n- [core action 1]\n- [core action 2]\n- [core action 3]\n\nDesign: [visual style or mood]\nHow it should feel: [how it should feel to use]\n```\n\n**Example:**\n\n```\nBuild a recipe organizer where I can:\n- Add recipes with title, ingredients, and instructions\n- Tag recipes by cuisine or meal type\n- Search by ingredient or tag\n\nDesign: Clean and modern\nHow it should feel: Easy to scan and quick to add new recipes\n```\n\nPaste your prompt into the composer and send it, in **Build** mode the agent starts working right away.\n\nYou'll see a working app in under 20 minutes.\n\n---\n\n## If something looks wrong\n\nAfter the first build, test the app in the preview pane. If a feature is missing or broken, describe the issue in chat - the agent will fix it. When you're ready to take it live, see [Publish your app](/put-your-app-live).\n\nFor more on the full workflow, see the next article in this path.\n\n**Go deeper:** [What kind of apps you can build?](/what-kind-of-apps-you-can-build) · [What is a Job?](/what-is-a-job)\n","published_title":"Start with your idea","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"f20c76cc-bf77-4d16-bc25-83cd9d29c91f","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Talk it through first","slug":"talk-it-through","content":"\n\n\nEmergent agents can talk through your idea before writing a single line of code. This article shows when to discuss, how a discussion turns into a build with Plan mode, and why talking first usually costs you less.\n\n---\n\n## Discussion uses fewer credits than building\n\nEvery agent turn bills per token, including planning and discussion (see [How credits work](/how-credits-work-basics)). But a discussion turn produces far less output than a build turn, so talking an idea through draws down noticeably **fewer** credits than building does. It is not free, it is the cheap part.\n\nThe agent can also help you decide which app type fits your project (Full Stack App, Mobile App, Landing Page, or Brainstorm) before you commit.\n\n<Callout type=\"tip\" title=\"Ask before you build\">\nIf you're unsure whether your idea needs a database, user logins, or connections to other services, just ask. The agent will help you choose the right starting point.\n</Callout>\n\n---\n\n## When to discuss vs. jump straight in\n\n**Start with a discussion if:**\n\n- You're not sure exactly what you want yet (explore options, compare approaches).\n- You need to decide between Full Stack App, Mobile App, or Landing Page app types and want guidance on which capabilities you'll actually need.\n- Your project involves integrations, scheduling, or connections to other services and you want to understand what's possible before committing.\n- You want the agent to sketch a rough plan or structure before generating files.\n\n**Jump straight to building if:**\n\n- You have a clear, specific request: \"Build a landing page with a hero section and email signup form.\"\n- You've already chosen the right app type and know your project requirements.\n- You're iterating on an existing app and just need a quick feature add.\n\nA short discussion often saves credits later by ensuring the agent sets up the right structure from the start.\n\n---\n\n## Plan mode: see the plan before any code\n\nFor anything non-trivial, use **Plan mode**, the composer has a **Build / Plan switcher** (a pill-shaped toggle; you can also press **⌥P**). In **Build** mode (the default), the agent starts working as soon as you send your prompt. In **Plan** mode, it doesn't build yet:\n\n1. Send your prompt with the switcher set to **Plan**.\n2. The agent produces its proposed approach as a **plan proposal card** in the chat.\n3. The card gives you two options, **Request changes** or **Looks good, let's build it**. Use whichever suits you: request changes as many times as you need, and when the plan looks right, approve it.\n4. Only when you approve does the agent start building, and the [chat-to-publish flow](/the-chat-to-deployment-flow) begins.\n\nPlan mode already knows the whole context of your app, so it's also the easiest way to shape a rough idea into a clear plan.\n\n<Callout type=\"note\" title=\"Availability\">\nPlan mode is not available in Brainstorm and E3 sessions.\n</Callout>\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/e09e1e25c4e34212ae1e751f2888970d.png\" alt=\"Where to find plan mode\" caption=\"Where to find plan mode\" />\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/3baa4d7ffb04401781e71903fe753173.png\" alt=\"Options after plan mode\" caption=\"Options after plan mode\" />\n\n\n\n<Callout type=\"note\" title=\"Maxx mode uses more credits\">\nWhen you enable **Maxx mode**, the agent plans more thoroughly and runs deeper validation. This produces higher-quality results but consumes significantly more credits. Maxx mode is available on Pro plans only. Save Maxx for the final build, not the planning phase.\n</Callout>\n\n---\n\n## If something looks wrong\n\nIf the agent seems to be generating code during a planning conversation when you only wanted to talk, just say:\n\n> \"Wait - I'm not ready to build yet. I just want to discuss options.\"\n\nThe agent will stop and switch back to advisory mode. You can continue the discussion and restart when you're ready.\n\n\n**Go deeper:** [Understanding models (E1/E2/E3 & Maxx)](/understanding-models-e1-e2-e3-maxx)","order":107,"parent_id":null,"icon":"message","description":"Not sure yet? Discuss your idea with the agent before building - it costs nothing.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-10-05T14:28:15.115630+00:00","published_at":"2026-10-05T14:28:15.115630+00:00","published_content":"\n\n\nEmergent agents can talk through your idea before writing a single line of code. This article shows when to discuss, how a discussion turns into a build with Plan mode, and why talking first usually costs you less.\n\n---\n\n## Discussion uses fewer credits than building\n\nEvery agent turn bills per token, including planning and discussion (see [How credits work](/how-credits-work-basics)). But a discussion turn produces far less output than a build turn, so talking an idea through draws down noticeably **fewer** credits than building does. It is not free, it is the cheap part.\n\nThe agent can also help you decide which app type fits your project (Full Stack App, Mobile App, Landing Page, or Brainstorm) before you commit.\n\n<Callout type=\"tip\" title=\"Ask before you build\">\nIf you're unsure whether your idea needs a database, user logins, or connections to other services, just ask. The agent will help you choose the right starting point.\n</Callout>\n\n---\n\n## When to discuss vs. jump straight in\n\n**Start with a discussion if:**\n\n- You're not sure exactly what you want yet (explore options, compare approaches).\n- You need to decide between Full Stack App, Mobile App, or Landing Page app types and want guidance on which capabilities you'll actually need.\n- Your project involves integrations, scheduling, or connections to other services and you want to understand what's possible before committing.\n- You want the agent to sketch a rough plan or structure before generating files.\n\n**Jump straight to building if:**\n\n- You have a clear, specific request: \"Build a landing page with a hero section and email signup form.\"\n- You've already chosen the right app type and know your project requirements.\n- You're iterating on an existing app and just need a quick feature add.\n\nA short discussion often saves credits later by ensuring the agent sets up the right structure from the start.\n\n---\n\n## Plan mode: see the plan before any code\n\nFor anything non-trivial, use **Plan mode**, the composer has a **Build / Plan switcher** (a pill-shaped toggle; you can also press **⌥P**). In **Build** mode (the default), the agent starts working as soon as you send your prompt. In **Plan** mode, it doesn't build yet:\n\n1. Send your prompt with the switcher set to **Plan**.\n2. The agent produces its proposed approach as a **plan proposal card** in the chat.\n3. The card gives you two options, **Request changes** or **Looks good, let's build it**. Use whichever suits you: request changes as many times as you need, and when the plan looks right, approve it.\n4. Only when you approve does the agent start building, and the [chat-to-publish flow](/the-chat-to-deployment-flow) begins.\n\nPlan mode already knows the whole context of your app, so it's also the easiest way to shape a rough idea into a clear plan.\n\n<Callout type=\"note\" title=\"Availability\">\nPlan mode is not available in Brainstorm and E3 sessions.\n</Callout>\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/e09e1e25c4e34212ae1e751f2888970d.png\" alt=\"Where to find plan mode\" caption=\"Where to find plan mode\" />\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/3baa4d7ffb04401781e71903fe753173.png\" alt=\"Options after plan mode\" caption=\"Options after plan mode\" />\n\n\n\n<Callout type=\"note\" title=\"Maxx mode uses more credits\">\nWhen you enable **Maxx mode**, the agent plans more thoroughly and runs deeper validation. This produces higher-quality results but consumes significantly more credits. Maxx mode is available on Pro plans only. Save Maxx for the final build, not the planning phase.\n</Callout>\n\n---\n\n## If something looks wrong\n\nIf the agent seems to be generating code during a planning conversation when you only wanted to talk, just say:\n\n> \"Wait - I'm not ready to build yet. I just want to discuss options.\"\n\nThe agent will stop and switch back to advisory mode. You can continue the discussion and restart when you're ready.\n\n\n**Go deeper:** [Understanding models (E1/E2/E3 & Maxx)](/understanding-models-e1-e2-e3-maxx)","published_title":"Talk it through first","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"efa33813-f8bc-4589-8a7d-b0e9ab72b3f0","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Watch your app come alive","slug":"watch-your-app-come-alive","content":"In the next few minutes, you'll watch Emergent's AI agent turn your description into a real, working app - no coding required.\n\n## Choose how to start: Build or Plan\n\nThe composer has a **Build / Plan switcher** (a pill-shaped toggle; **⌥P** also toggles it):\n\n- **Build** (the default), the agent starts working as soon as you send your prompt. No waiting on plan approval; it gets going immediately.\n- **Plan**: the agent first presents its proposed approach as a **plan proposal card** with two options: **Request changes** or **Looks good, let's build it**. Nothing is built until you approve. Use whichever option suits you.\n\nFor your first build, Plan mode is the safer start, you see the full picture and can refine it before the main build work begins.\n\n<Callout type=\"success\" title=\"Adjust the plan before work begins\">\nPlan mode lets you review and adjust what the agent intends to build before it starts generating code. Note that planning itself also bills per token, a plan turn is much smaller than a build turn, but it isn't free (see [How credits work](/how-credits-work-basics)).\n</Callout>\n\n<Callout type=\"note\" title=\"Availability\">\nPlan mode is not available in Brainstorm and E3 sessions.\n</Callout>\n\n## Watch the agent work\n\nOnce the build starts, you'll see a live stream of steps in the chat:\n\n- **Planning** - breaking your idea into components and features, the agent might ask you questions like \"Do you need users to login?\" or \"Any additional info?\" or questions about the features of the app here.\n- **Scaffolding** - creating the project structure and installing tools\n- **Implementation** - writing the code that makes your app work\n- **Testing** - checking for errors automatically\n\nThe first build usually takes a few minutes. The agent works autonomously - you don't need to approve every step.\n\n<Callout type=\"note\" title=\"Checkpoints save your progress\">\nThe platform automatically saves checkpoints of your app as the agent works. If a change breaks something, you can roll back from the **chat timeline**, note that rolling back erases the messages and code changes (optional) after the point you choose, so you roll back to a state, not \"undo one thing.\" See [Checkpoints: undo anything](/checkpoints-undo-anything).\n</Callout>\n\n## Your first preview\n\nAs soon as the agent finishes, a **live preview** appears. This is your app, running in real time. You can click through it, test features, and see exactly what you built.\n\nWhen the build round completes, the agent will print a short summary in the chat recapping what it created or changed - then it invites you to open your app and try it out. The preview updates automatically whenever the agent makes changes - no refresh needed.\n\nTry interacting with your app like a real user would: tap buttons, fill in forms, navigate between pages. If something doesn't look or work the way you expected, just describe the change in chat and the agent will fix it.\n\n<Callout type=\"warning\" title=\"Preview vs your live app\">\nThe preview is separate from your live app (production). Changes you see in the preview won't appear in production until you explicitly **Publish** (first time) or **Re-publish** (updates). The preview is your testing playground; publishing is when it goes live for real. See [Put your app live](/put-your-app-live).\n</Callout>\n\n## If something looks wrong\n\nIf the agent stops or the preview doesn't match what you asked for, you have options:\n\n- **Describe the issue in chat** and the agent will iterate. Be specific: \"Move the search bar to the top\" works better than \"the design of the app looks off.\"\n- **Roll back** if a recent change broke something that was working. Use the **Rollback button in the chat timeline** on the message you want to revert to.\n- **Ask the agent to explain what it built** if you're not sure why something works the way it does.\n\nThe agent learns from your feedback and adjusts as you go.\n\n<Callout type=\"tip\">\nStart small. Your first build should be something you can describe in a few sentences. You can always add more features later - it's faster to build in layers than to fix a big, complicated first attempt.\n</Callout>\n\n\n**Go deeper:** [The chat-to-publish flow](/the-chat-to-deployment-flow) · [Previewing & iterating](/previewing-iterating)","order":108,"parent_id":null,"icon":"eye","description":"See your idea turn into a real, working app in minutes.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-09-24T14:08:37.245126+00:00","published_at":"2026-09-24T14:08:37.245126+00:00","published_content":"In the next few minutes, you'll watch Emergent's AI agent turn your description into a real, working app - no coding required.\n\n## Choose how to start: Build or Plan\n\nThe composer has a **Build / Plan switcher** (a pill-shaped toggle; **⌥P** also toggles it):\n\n- **Build** (the default), the agent starts working as soon as you send your prompt. No waiting on plan approval; it gets going immediately.\n- **Plan**: the agent first presents its proposed approach as a **plan proposal card** with two options: **Request changes** or **Looks good, let's build it**. Nothing is built until you approve. Use whichever option suits you.\n\nFor your first build, Plan mode is the safer start, you see the full picture and can refine it before the main build work begins.\n\n<Callout type=\"success\" title=\"Adjust the plan before work begins\">\nPlan mode lets you review and adjust what the agent intends to build before it starts generating code. Note that planning itself also bills per token, a plan turn is much smaller than a build turn, but it isn't free (see [How credits work](/how-credits-work-basics)).\n</Callout>\n\n<Callout type=\"note\" title=\"Availability\">\nPlan mode is not available in Brainstorm and E3 sessions.\n</Callout>\n\n## Watch the agent work\n\nOnce the build starts, you'll see a live stream of steps in the chat:\n\n- **Planning** - breaking your idea into components and features, the agent might ask you questions like \"Do you need users to login?\" or \"Any additional info?\" or questions about the features of the app here.\n- **Scaffolding** - creating the project structure and installing tools\n- **Implementation** - writing the code that makes your app work\n- **Testing** - checking for errors automatically\n\nThe first build usually takes a few minutes. The agent works autonomously - you don't need to approve every step.\n\n<Callout type=\"note\" title=\"Checkpoints save your progress\">\nThe platform automatically saves checkpoints of your app as the agent works. If a change breaks something, you can roll back from the **chat timeline**, note that rolling back erases the messages and code changes (optional) after the point you choose, so you roll back to a state, not \"undo one thing.\" See [Checkpoints: undo anything](/checkpoints-undo-anything).\n</Callout>\n\n## Your first preview\n\nAs soon as the agent finishes, a **live preview** appears. This is your app, running in real time. You can click through it, test features, and see exactly what you built.\n\nWhen the build round completes, the agent will print a short summary in the chat recapping what it created or changed - then it invites you to open your app and try it out. The preview updates automatically whenever the agent makes changes - no refresh needed.\n\nTry interacting with your app like a real user would: tap buttons, fill in forms, navigate between pages. If something doesn't look or work the way you expected, just describe the change in chat and the agent will fix it.\n\n<Callout type=\"warning\" title=\"Preview vs your live app\">\nThe preview is separate from your live app (production). Changes you see in the preview won't appear in production until you explicitly **Publish** (first time) or **Re-publish** (updates). The preview is your testing playground; publishing is when it goes live for real. See [Put your app live](/put-your-app-live).\n</Callout>\n\n## If something looks wrong\n\nIf the agent stops or the preview doesn't match what you asked for, you have options:\n\n- **Describe the issue in chat** and the agent will iterate. Be specific: \"Move the search bar to the top\" works better than \"the design of the app looks off.\"\n- **Roll back** if a recent change broke something that was working. Use the **Rollback button in the chat timeline** on the message you want to revert to.\n- **Ask the agent to explain what it built** if you're not sure why something works the way it does.\n\nThe agent learns from your feedback and adjusts as you go.\n\n<Callout type=\"tip\">\nStart small. Your first build should be something you can describe in a few sentences. You can always add more features later - it's faster to build in layers than to fix a big, complicated first attempt.\n</Callout>\n\n\n**Go deeper:** [The chat-to-publish flow](/the-chat-to-deployment-flow) · [Previewing & iterating](/previewing-iterating)","published_title":"Watch your app come alive","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"6c95e4b2-622a-4259-b022-34c4923a0bf3","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Make it yours","slug":"make-it-yours","content":"\nYou'll learn the golden rule of customization: make every request **clear**, say exactly what to change, where it is, and what it should look like afterwards. Screenshots help enormously.\n\n## The golden rule: be clear and as specific as you can\n\nYou can ask for several changes in one message, the agent handles that fine, as long as each change is unmistakably clear. What breaks iteration is vagueness, not volume.\n\nCompare:\n\n- ❌ \"Make the design better\"\n- ✅ \"Three changes: (1) move the Sign In button to the top-right corner and make it blue, (2) change the page background to light blue, (3) make the product title text bigger.\"\n\nThe agent updates the preview automatically after each round. You'll see the result in seconds, and you can immediately ask for the next round - or undo what you just tried.\n\n## Do's and don'ts of prompting\n\n**Do:**\n\n- Name the element and its location: \"the card at the top of the page\", \"the text under the photo\", \"the menu icon on the left side\".\n- Say what the end state should be, not just what's wrong: \"move it to the top-right\" beats \"it's in the wrong place\".\n- **Upload a screenshot** when words aren't enough, drag the image into chat and add a short note like \"this spacing looks too tight\" or \"the text is cut off here\".\n- Paste the **full error message** when something breaks (right-click → Copy in your browser console), with a one-line prompt like \"please solve this error\".\n- Bundle related changes in one clear, numbered message.\n\n**Don't:**\n\n- Send vague requests like \"improve it\" or \"the button looks wrong\", the agent has to guess.\n- Paste API keys or other secrets into chat, they belong in your project's secrets, never in messages (see [Keep it safe](/keep-it-safe)).\n- Mix a bug report and a redesign in one breath without separating them, number them so each gets addressed.\n\n## Edit visually with Canvas edit\n\nIn the **preview pane**, there is a **Canvas edit** option available for making visual tweaks directly on the page.\nYou can click the Edit button in the canvas and select a particular design element, a chat window will appear and you can describe your changes there regarding that particular element, and the agent makes the changes in chat.\n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/1411fab02f634c85aa23be21e7f1d995.mov\" />\n\n\n## Keep iterating or start fresh\n\nEvery change builds on the last one. If a tweak didn't land the way you hoped, just ask again:\n\n- \"Actually, move that button back to the left\"\n- \"Make the text a bit smaller - that's too big\"\n- \"Go back to the original color\"\n\nYou can cycle through options as many times as you need. The preview updates each time, so you'll know immediately when something clicks.\n\nIf you've gone down a rabbit hole and want to reset, describe your original vision again in a fresh message. The agent will re-approach the design from scratch. Or you can roll back to a previous state.\n\n## If something looks wrong\n\nFor layout problems - text cut off, buttons hidden, spacing gone wrong - a screenshot often works better than words. The agent will inspect the component and adjust the styles.\n\nThe preview and your live app are **completely separate**. Changes you see in the preview do *not* automatically appear in production. Until you **Re-publish**, your live app keeps running the last version you published - even if the preview shows something totally different.\n\n\n**Go deeper:** [Previewing & iterating](/previewing-iterating)","order":109,"parent_id":null,"icon":"palette","description":"Change colors, text, and features by asking - one change at a time.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-10-05T14:28:16.700183+00:00","published_at":"2026-10-05T14:28:16.700183+00:00","published_content":"\nYou'll learn the golden rule of customization: make every request **clear**, say exactly what to change, where it is, and what it should look like afterwards. Screenshots help enormously.\n\n## The golden rule: be clear and as specific as you can\n\nYou can ask for several changes in one message, the agent handles that fine, as long as each change is unmistakably clear. What breaks iteration is vagueness, not volume.\n\nCompare:\n\n- ❌ \"Make the design better\"\n- ✅ \"Three changes: (1) move the Sign In button to the top-right corner and make it blue, (2) change the page background to light blue, (3) make the product title text bigger.\"\n\nThe agent updates the preview automatically after each round. You'll see the result in seconds, and you can immediately ask for the next round - or undo what you just tried.\n\n## Do's and don'ts of prompting\n\n**Do:**\n\n- Name the element and its location: \"the card at the top of the page\", \"the text under the photo\", \"the menu icon on the left side\".\n- Say what the end state should be, not just what's wrong: \"move it to the top-right\" beats \"it's in the wrong place\".\n- **Upload a screenshot** when words aren't enough, drag the image into chat and add a short note like \"this spacing looks too tight\" or \"the text is cut off here\".\n- Paste the **full error message** when something breaks (right-click → Copy in your browser console), with a one-line prompt like \"please solve this error\".\n- Bundle related changes in one clear, numbered message.\n\n**Don't:**\n\n- Send vague requests like \"improve it\" or \"the button looks wrong\", the agent has to guess.\n- Paste API keys or other secrets into chat, they belong in your project's secrets, never in messages (see [Keep it safe](/keep-it-safe)).\n- Mix a bug report and a redesign in one breath without separating them, number them so each gets addressed.\n\n## Edit visually with Canvas edit\n\nIn the **preview pane**, there is a **Canvas edit** option available for making visual tweaks directly on the page.\nYou can click the Edit button in the canvas and select a particular design element, a chat window will appear and you can describe your changes there regarding that particular element, and the agent makes the changes in chat.\n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/1411fab02f634c85aa23be21e7f1d995.mov\" />\n\n\n## Keep iterating or start fresh\n\nEvery change builds on the last one. If a tweak didn't land the way you hoped, just ask again:\n\n- \"Actually, move that button back to the left\"\n- \"Make the text a bit smaller - that's too big\"\n- \"Go back to the original color\"\n\nYou can cycle through options as many times as you need. The preview updates each time, so you'll know immediately when something clicks.\n\nIf you've gone down a rabbit hole and want to reset, describe your original vision again in a fresh message. The agent will re-approach the design from scratch. Or you can roll back to a previous state.\n\n## If something looks wrong\n\nFor layout problems - text cut off, buttons hidden, spacing gone wrong - a screenshot often works better than words. The agent will inspect the component and adjust the styles.\n\nThe preview and your live app are **completely separate**. Changes you see in the preview do *not* automatically appear in production. Until you **Re-publish**, your live app keeps running the last version you published - even if the preview shows something totally different.\n\n\n**Go deeper:** [Previewing & iterating](/previewing-iterating)","published_title":"Make it yours","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"05d10548-4e61-4133-b5ca-92f189c12953","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Try it before you share it","slug":"try-it-before-you-share-it","content":"\n\nBefore you share your app with the world, you'll test it the way a real user would, and let the agent and the platform run their own checks too.\n\n## 1. Walk through your app like a visitor\n\nOpen the live preview (see [Previewing & iterating](/previewing-iterating) if you need a refresher) and test like a visitor would:\n\n- **Click every button** - navigation links, submit buttons, \"Learn More\" cards - to make sure they all do something.\n- **Alignment** - Check if any alignment issues when you change screen sizes or zoom or open in a new tab or incognito tabs.\n- **Fill out forms** - type into fields, pick dropdowns, toggle checkboxes. Hit submit and watch for success messages or errors.\n- **Test full flows**- if you have set up OTP or payment flows (or any other process flows), check them end to end: whether OTPs are generated, each time it is different, payments are landing correctly etc.\n- **Navigate between pages** - use menus, back buttons, and links to move around. Nothing should break or show a blank screen.\n- **Footers** - if required, add links to terms & conditions, legal policies, contact, social media etc at the bottom of the page and verify the links work\n\n## 2. Quick visual & data checklist\n\nBefore you publish or share the link, scan for these common gotchas:\n\n- **Images load** - no broken placeholders or missing icons.\n-- **Uploads work** - if your app asks the user to upload something, verify the uploads work, and do resolution and format checks.\n- **Text is readable** - font sizes work on small screens, colors have enough contrast.\n- **Forms validate** - try submitting empty fields or wrong formats (like \"abc\" in an email box). The app should show helpful error messages.\n- **Data appears** - if your app fetches data (from its database or a connected service), confirm it shows up. Check the browser console for red error messages if something's missing.\n\n\n\n## 3. Let the agent test it\n\nYou can ask the agent to test what it built (but don't skip the manual checks after this):\n\n```\nTest the app end to end and report anything broken\n```\n\nThe agent has a built-in testing capability and runs checks toward the end of a build; asking explicitly makes it exercise the flows you care about. For how the agent uses your feedback to debug, see [Debugging & testing with the agent](/debugging-testing-with-the-agent).\n\n\n\n## 4. Check it on a real device\n\n- Click the view(desktop/mobile/tablet) button in the preview pane, or open the preview URL on your phone. Make sure text doesn't overlap, buttons aren't cut off, and everything still works.\n- Check the web app works cross-platform: windows vs mac, android vs iOS. \n- Building a **mobile app**? Open the **Expo Go** app - newer projects sign in with a device code, older ones scan the QR code from the preview panel (from inside Expo Go, not your camera app), see [Pre-publish health check](/pre-publish-health-check) for the full walkthrough. \n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/b696350308a947b69fe53ecf695a6ae1.mov\" />\n\n\n## Report what's broken\n\nWhen you find a bug, describe **exactly what you did, what you expected, and what actually happened** in the chat. The more detail you give, the faster the agent can fix it.\n\n**Good example:**\n\n```\nI clicked the \"Add to Cart\" button on the product detail page.\nI expected the item count in the cart icon to go up, but nothing happened.\nScreenshot attached.\n```\n\n**Not enough detail:**\n\n```\nThe button doesn't work.\n```\n\n\nIf the issue is visual, attach a screenshot (drag the image into the chat). If you see red text in the browser console (right-click anywhere on the page → Inspect → Console tab), **copy the entire error message**, right-click the error and select \"Copy\" to grab the full output including the stack trace, and paste it into the chat. Then tell the agent exactly how to trigger the bug:\n\n- Which page were you on?\n- What did you click or type?\n- Did it happen the first time, or only after doing something else first?\n\nThis context helps the agent fix issues that only show up under certain conditions.\n\n## If something still looks wrong after a fix\n\nThe agent will rebuild the preview after every change. Give it a few seconds, then **test the same flow again** to confirm the fix worked. If the bug persists:\n\n- Try the steps one more time - be extra specific about what's still broken.\n- Check if the error message changed (that means the agent is making progress).\n- If you're stuck after a couple of rounds, [When something breaks](/when-something-breaks) has the full triage path, including how to tell a config problem from a code problem, and what to send support.\n\nOnce everything works smoothly in the preview, you're ready to publish and share it with real users.\n\n\n**Go deeper:** [Pre-publish health check for web apps](/pre-deploy-pre-publish-health-check)","order":110,"parent_id":null,"icon":"check-circle","description":"Click through your app like a real user and catch anything odd.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-10-05T14:28:18.867748+00:00","published_at":"2026-10-05T14:28:18.867748+00:00","published_content":"\n\nBefore you share your app with the world, you'll test it the way a real user would, and let the agent and the platform run their own checks too.\n\n## 1. Walk through your app like a visitor\n\nOpen the live preview (see [Previewing & iterating](/previewing-iterating) if you need a refresher) and test like a visitor would:\n\n- **Click every button** - navigation links, submit buttons, \"Learn More\" cards - to make sure they all do something.\n- **Alignment** - Check if any alignment issues when you change screen sizes or zoom or open in a new tab or incognito tabs.\n- **Fill out forms** - type into fields, pick dropdowns, toggle checkboxes. Hit submit and watch for success messages or errors.\n- **Test full flows**- if you have set up OTP or payment flows (or any other process flows), check them end to end: whether OTPs are generated, each time it is different, payments are landing correctly etc.\n- **Navigate between pages** - use menus, back buttons, and links to move around. Nothing should break or show a blank screen.\n- **Footers** - if required, add links to terms & conditions, legal policies, contact, social media etc at the bottom of the page and verify the links work\n\n## 2. Quick visual & data checklist\n\nBefore you publish or share the link, scan for these common gotchas:\n\n- **Images load** - no broken placeholders or missing icons.\n-- **Uploads work** - if your app asks the user to upload something, verify the uploads work, and do resolution and format checks.\n- **Text is readable** - font sizes work on small screens, colors have enough contrast.\n- **Forms validate** - try submitting empty fields or wrong formats (like \"abc\" in an email box). The app should show helpful error messages.\n- **Data appears** - if your app fetches data (from its database or a connected service), confirm it shows up. Check the browser console for red error messages if something's missing.\n\n\n\n## 3. Let the agent test it\n\nYou can ask the agent to test what it built (but don't skip the manual checks after this):\n\n```\nTest the app end to end and report anything broken\n```\n\nThe agent has a built-in testing capability and runs checks toward the end of a build; asking explicitly makes it exercise the flows you care about. For how the agent uses your feedback to debug, see [Debugging & testing with the agent](/debugging-testing-with-the-agent).\n\n\n\n## 4. Check it on a real device\n\n- Click the view(desktop/mobile/tablet) button in the preview pane, or open the preview URL on your phone. Make sure text doesn't overlap, buttons aren't cut off, and everything still works.\n- Check the web app works cross-platform: windows vs mac, android vs iOS. \n- Building a **mobile app**? Open the **Expo Go** app - newer projects sign in with a device code, older ones scan the QR code from the preview panel (from inside Expo Go, not your camera app), see [Pre-publish health check](/pre-publish-health-check) for the full walkthrough. \n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/b696350308a947b69fe53ecf695a6ae1.mov\" />\n\n\n## Report what's broken\n\nWhen you find a bug, describe **exactly what you did, what you expected, and what actually happened** in the chat. The more detail you give, the faster the agent can fix it.\n\n**Good example:**\n\n```\nI clicked the \"Add to Cart\" button on the product detail page.\nI expected the item count in the cart icon to go up, but nothing happened.\nScreenshot attached.\n```\n\n**Not enough detail:**\n\n```\nThe button doesn't work.\n```\n\n\nIf the issue is visual, attach a screenshot (drag the image into the chat). If you see red text in the browser console (right-click anywhere on the page → Inspect → Console tab), **copy the entire error message**, right-click the error and select \"Copy\" to grab the full output including the stack trace, and paste it into the chat. Then tell the agent exactly how to trigger the bug:\n\n- Which page were you on?\n- What did you click or type?\n- Did it happen the first time, or only after doing something else first?\n\nThis context helps the agent fix issues that only show up under certain conditions.\n\n## If something still looks wrong after a fix\n\nThe agent will rebuild the preview after every change. Give it a few seconds, then **test the same flow again** to confirm the fix worked. If the bug persists:\n\n- Try the steps one more time - be extra specific about what's still broken.\n- Check if the error message changed (that means the agent is making progress).\n- If you're stuck after a couple of rounds, [When something breaks](/when-something-breaks) has the full triage path, including how to tell a config problem from a code problem, and what to send support.\n\nOnce everything works smoothly in the preview, you're ready to publish and share it with real users.\n\n\n**Go deeper:** [Pre-publish health check for web apps](/pre-deploy-pre-publish-health-check)","published_title":"Try it before you share it","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"f8320b81-dcef-4918-8bd9-e8e3436c58ac","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Put your app live","slug":"put-your-app-live","content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nOne click turns your preview into a real, live website anyone can visit - at a permanent web address that stays up 24/7.\n\n---\n\n## Two environments: Preview and Production\n\nBefore the buttons make sense, know the two places your app exists:\n\n- **Preview**: your private workspace copy, where you and the agent build and test. It sleeps after ~30 minutes of inactivity and is not meant for real users.\n- **Production**: your **live app**: the public version running 24/7 at its own web address (like `https://your-app-name.emergent.host`). It only ever changes when you publish.\n\nEverything below is about moving your app from Preview to Production.\n\n---\n\n## Which button, when?\n\n| You want to… | Use | What happens |\n|---|---|---|\n| Build, test, and iterate | **Preview** | Your workspace copy updates as the agent works. Nothing is public. |\n| Take the app live for the first time | **Publish** | Emergent packages your app and puts it on its own permanent web address. Your publishing tier's monthly credit fee starts. |\n| Push your latest preview changes to the live app (in the same job) | **Re-publish** | The live app updates to your current preview code with zero downtime. The address stays the same. Re-publishing does not add a new tier fee.  |\n| Put a **different job** live at this same app (only for forked jobs) | **Replace** | A zero-downtime swap: the other job takes over the live address (you choose whether to keep the existing database or start fresh). |\n\nOne button drives all of this: the top-toolbar button reads **Publish** (first time) and **Re-publish** once you're live, and clicking **Re-publish** doesn't immediately push anything: it opens the **Manage Publishing** panel, where you confirm updates, manage domains, secrets, and shutdown.\n\n---\n\n## Making your app live\n\n<Steps>\n\n<Step title=\"Click Publish\">\nIn the workspace, find the **Publish** button. This starts the process - Emergent sets up the infrastructure and packages your app for the web.\n</Step>\n\n<Step title=\"Wait for the build\">\nThe first time takes around **15 minutes** while the platform sets up servers, runs health checks, and spins up your app. Grab a coffee - you'll see progress updates in the workspace.\n</Step>\n\n<Step title=\"Get your live web address\">\nWhen it finishes, you'll receive a permanent, public web address like `https://your-app-name.emergent.host`. This link works immediately and stays live as long as your app is running.\n</Step>\n\n</Steps>\n\n\n<Callout type=\"success\" title=\"Your app is live\">\nShare the web address with anyone - no login required unless you've built authentication into your app. The link is permanent and won't change when you update your app later.\n</Callout>\n\n---\n\n## Your live app runs separately from preview\n\nWhen you make changes in preview - fixing a bug, tweaking how it looks, adding a feature - those updates stay in preview only. Your live app keeps serving the last version you published, so you never accidentally break things for real users while you're still experimenting.\n\nTo push updates to your live app, click **Re-publish**. Details in [Preview vs Published](/preview-vs-deployed-separate).\n\n<Callout type=\"note\" title=\"Safe iteration\">\nThis separation means you can test freely in preview without worrying about your live users. Publish updates only when you're ready.\n</Callout>\n\n---\n\n## What it costs to keep your app live\n\nA live app costs **50-1,100 credits per month** (depending on your publishing tier) while it's running. This covers hosting, bandwidth, health monitoring, and automatic scaling.\n\nFor details on topping up credits, see [Managing credit usage](/managing-credit-usage).\n\n---\n\n## Taking your app offline\n\nYou can take your live app offline at any time, and it does **not** touch your subscription.\n\n<Callout type=\"success\" title=\"Shutting down is not unsubscribing\">\nTaking an app offline only stops **that app's** monthly hosting charge. Your subscription, your credit balance, your project, its code, and its chat history are all untouched. You can bring the app back online whenever you like.\n</Callout>\n\n<Steps>\n\n<Step title=\"Open Manage Publishing\">\nIn the top toolbar of your app, click **Re-publish**.\n\n![Click Re-publish](https://files.emergentagent.com/visual_guide/shutdown_deployment/sdd-1.png)\n</Step>\n\n<Step title=\"Shut it down\">\nIn the **Overview** tab, scroll down to the **\"Take app offline\"** row and click **Shutdown**, the app is taken offline.\n\n![Click Shutdown to take app offline](https://files.emergentagent.com/visual_guide/shutdown_deployment/sdd-2.png)\n</Step>\n\n</Steps>\n\n### What stops, what stays\n\n| Stops immediately | Stays |\n|---|---|\n| The app being reachable at its web address | Your project, code, and chat history |\n| The monthly publish (hosting) charge | Your subscription and credit balance |\n| | Your preview workspace, you can keep building |\n\n<Callout type=\"warning\" title=\"Databases are not deleted\">\nShutting down does not delete any databases or external services your app uses. If you want to remove data, delete those resources separately. See [Database (MongoDB)](/database-mongodb).\n</Callout>\n\n### Custom domains, and coming back\n\n- If a **custom domain** is linked to this app, shutting down **removes the link**, it is **not** restored automatically when you publish again. Re-add the domain in the **Domain tab** afterwards. See [Use your own web address](/use-your-own-web-address).\n- To bring the app back online, click **Publish** again. The revived publish starts on the **base tier**, if you had upgraded the publishing tier before, set it again after publishing.\n- If the app still responds at its address a minute after shutdown, refresh without cache or try a private browser window. If it persists, contact [support@emergent.sh](mailto:support@emergent.sh).\n\n---\n\n## If something looks wrong\n\nAfter your first publish, open the web address in a fresh browser tab (or on your phone) and walk through your app as a user would. The live version is optimized differently from preview, so it's worth a quick check.\n\nIf you spot an issue, make the fix in preview, test it thoroughly, then **Re-publish**. The web address stays the same - your users won't notice anything except that the bug disappeared.\n\nFor monitoring tools, logs, and troubleshooting slow or crashed apps, see [Publishing your web app](/deploying-web).\n\n\n**Go deeper:** [Publishing plan levels](/deployment-plan-levels)","order":111,"parent_id":null,"icon":"rocket","description":"One click gets you a real link on the internet.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-09-24T14:08:37.258890+00:00","published_at":"2026-09-24T14:08:37.258890+00:00","published_content":"\n> **Coming from another platform?** Publishing is the same thing as *deploying* - what other tools call deploy, deployment, or redeploy, Emergent calls **Publish** and **Re-publish**.\n\nOne click turns your preview into a real, live website anyone can visit - at a permanent web address that stays up 24/7.\n\n---\n\n## Two environments: Preview and Production\n\nBefore the buttons make sense, know the two places your app exists:\n\n- **Preview**: your private workspace copy, where you and the agent build and test. It sleeps after ~30 minutes of inactivity and is not meant for real users.\n- **Production**: your **live app**: the public version running 24/7 at its own web address (like `https://your-app-name.emergent.host`). It only ever changes when you publish.\n\nEverything below is about moving your app from Preview to Production.\n\n---\n\n## Which button, when?\n\n| You want to… | Use | What happens |\n|---|---|---|\n| Build, test, and iterate | **Preview** | Your workspace copy updates as the agent works. Nothing is public. |\n| Take the app live for the first time | **Publish** | Emergent packages your app and puts it on its own permanent web address. Your publishing tier's monthly credit fee starts. |\n| Push your latest preview changes to the live app (in the same job) | **Re-publish** | The live app updates to your current preview code with zero downtime. The address stays the same. Re-publishing does not add a new tier fee.  |\n| Put a **different job** live at this same app (only for forked jobs) | **Replace** | A zero-downtime swap: the other job takes over the live address (you choose whether to keep the existing database or start fresh). |\n\nOne button drives all of this: the top-toolbar button reads **Publish** (first time) and **Re-publish** once you're live, and clicking **Re-publish** doesn't immediately push anything: it opens the **Manage Publishing** panel, where you confirm updates, manage domains, secrets, and shutdown.\n\n---\n\n## Making your app live\n\n<Steps>\n\n<Step title=\"Click Publish\">\nIn the workspace, find the **Publish** button. This starts the process - Emergent sets up the infrastructure and packages your app for the web.\n</Step>\n\n<Step title=\"Wait for the build\">\nThe first time takes around **15 minutes** while the platform sets up servers, runs health checks, and spins up your app. Grab a coffee - you'll see progress updates in the workspace.\n</Step>\n\n<Step title=\"Get your live web address\">\nWhen it finishes, you'll receive a permanent, public web address like `https://your-app-name.emergent.host`. This link works immediately and stays live as long as your app is running.\n</Step>\n\n</Steps>\n\n\n<Callout type=\"success\" title=\"Your app is live\">\nShare the web address with anyone - no login required unless you've built authentication into your app. The link is permanent and won't change when you update your app later.\n</Callout>\n\n---\n\n## Your live app runs separately from preview\n\nWhen you make changes in preview - fixing a bug, tweaking how it looks, adding a feature - those updates stay in preview only. Your live app keeps serving the last version you published, so you never accidentally break things for real users while you're still experimenting.\n\nTo push updates to your live app, click **Re-publish**. Details in [Preview vs Published](/preview-vs-deployed-separate).\n\n<Callout type=\"note\" title=\"Safe iteration\">\nThis separation means you can test freely in preview without worrying about your live users. Publish updates only when you're ready.\n</Callout>\n\n---\n\n## What it costs to keep your app live\n\nA live app costs **50-1,100 credits per month** (depending on your publishing tier) while it's running. This covers hosting, bandwidth, health monitoring, and automatic scaling.\n\nFor details on topping up credits, see [Managing credit usage](/managing-credit-usage).\n\n---\n\n## Taking your app offline\n\nYou can take your live app offline at any time, and it does **not** touch your subscription.\n\n<Callout type=\"success\" title=\"Shutting down is not unsubscribing\">\nTaking an app offline only stops **that app's** monthly hosting charge. Your subscription, your credit balance, your project, its code, and its chat history are all untouched. You can bring the app back online whenever you like.\n</Callout>\n\n<Steps>\n\n<Step title=\"Open Manage Publishing\">\nIn the top toolbar of your app, click **Re-publish**.\n\n![Click Re-publish](https://files.emergentagent.com/visual_guide/shutdown_deployment/sdd-1.png)\n</Step>\n\n<Step title=\"Shut it down\">\nIn the **Overview** tab, scroll down to the **\"Take app offline\"** row and click **Shutdown**, the app is taken offline.\n\n![Click Shutdown to take app offline](https://files.emergentagent.com/visual_guide/shutdown_deployment/sdd-2.png)\n</Step>\n\n</Steps>\n\n### What stops, what stays\n\n| Stops immediately | Stays |\n|---|---|\n| The app being reachable at its web address | Your project, code, and chat history |\n| The monthly publish (hosting) charge | Your subscription and credit balance |\n| | Your preview workspace, you can keep building |\n\n<Callout type=\"warning\" title=\"Databases are not deleted\">\nShutting down does not delete any databases or external services your app uses. If you want to remove data, delete those resources separately. See [Database (MongoDB)](/database-mongodb).\n</Callout>\n\n### Custom domains, and coming back\n\n- If a **custom domain** is linked to this app, shutting down **removes the link**, it is **not** restored automatically when you publish again. Re-add the domain in the **Domain tab** afterwards. See [Use your own web address](/use-your-own-web-address).\n- To bring the app back online, click **Publish** again. The revived publish starts on the **base tier**, if you had upgraded the publishing tier before, set it again after publishing.\n- If the app still responds at its address a minute after shutdown, refresh without cache or try a private browser window. If it persists, contact [support@emergent.sh](mailto:support@emergent.sh).\n\n---\n\n## If something looks wrong\n\nAfter your first publish, open the web address in a fresh browser tab (or on your phone) and walk through your app as a user would. The live version is optimized differently from preview, so it's worth a quick check.\n\nIf you spot an issue, make the fix in preview, test it thoroughly, then **Re-publish**. The web address stays the same - your users won't notice anything except that the bug disappeared.\n\nFor monitoring tools, logs, and troubleshooting slow or crashed apps, see [Publishing your web app](/deploying-web).\n\n\n**Go deeper:** [Publishing plan levels](/deployment-plan-levels)","published_title":"Put your app live","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"fc44539f-d547-4b31-a758-5f56ed8ed6c6","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Share it with the world","slug":"share-it-with-the-world","content":"\n\nYour app is live - now it's time to share the link, watch real people use it, and collect the feedback that'll help you make it even better.\n\n---\n\n## Share your public URL, the right one\n\nOnce your app is live, you have a **permanent public link** (something like `https://your-app-name.emergent.host`). Anyone can visit it - no login required unless you've built one into your app. Copy it from **Manage Publishing** (Click **Re-publish** to open, the link is shown in the panel header, with a **Visit** icon and **copy** icons on the side).\n\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/a1ea2076d7f64114a5161e91a0f3c66c.png\" alt=\"Manage Publishing panel\" caption=\"Manage Publishing panel\" />\n\n\n<Callout type=\"warning\" title=\"Share the live link, not the preview link\">\nYour **preview** URL (it ends in `emergentagent.com`) is for you: it's tied to your working session and the preview **sleeps after ~30 minutes of inactivity**, someone opening it later may find nothing there. Share the `emergent.host` link. The one exception: letting a friend try the app *before* you publish, open the preview in a new tab and share that link while you're both online, knowing it will sleep.\n</Callout>\n\nShare it however you like:\n\n- Text it to friends or family\n- Post it in a group chat or on social media\n- Email it to beta testers\n- Add it to your portfolio\n\nThe link stays the same as long as your app is live, so you can share it once and people can keep visiting. Your live app runs 24/7, visitors don't wait for it to \"wake up.\"\n\n---\n\n## What your visitors see\n\nWhen someone clicks your link, they see the exact version of your app that's currently live - the production environment. This is the polished, stable version you chose to publish (see [Preview vs Published](/preview-vs-deployed-separate) for the difference).\n\nIf you're still iterating in preview, those changes **won't** show up at the public URL until you **Re-publish**. Your live app stays frozen at the last version you published, so it's safe to keep experimenting in the background.\n\n---\n\n## Keep an eye on your live app\n\nEverything you need is in **Manage Publishing** (click **Re-publish** in the top toolbar):\n\n- The panel header shows your app's **Live badge** (green dot), its URL, and a **Visit** button.\n- **View Logs**: each published version in the Publishes section has a View Logs link for what's happening behind the scenes.\n- **Run health check**: the button in the bottom bar checks that your live app is responding properly.\n- **Enable alerts**: a toggle to get notified about publish events.\n- **Analytics**: the Analytics button in the panel header opens App Analytics: traffic for your live app across time ranges from the last 6 hours to the last 30 days. *(Currently available to Pro users.)*\n\nIf your app is crashing or running slowly, see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) for troubleshooting steps.\n\n---\n\n## Next step: your own web address\n\nSharing `your-app-name.emergent.host` is fine for testers, but if this app represents you or your business, the next upgrade is your own domain, like `myapp.com`. That's the next page: [Use your own web address](/use-your-own-web-address).\n","order":112,"parent_id":null,"icon":"send","description":"Send your link, get your first feedback, and see visits.","created_at":"2026-08-24T12:16:31.798003+00:00","updated_at":"2026-10-05T14:28:20.059644+00:00","published_at":"2026-10-05T14:28:20.059644+00:00","published_content":"\n\nYour app is live - now it's time to share the link, watch real people use it, and collect the feedback that'll help you make it even better.\n\n---\n\n## Share your public URL, the right one\n\nOnce your app is live, you have a **permanent public link** (something like `https://your-app-name.emergent.host`). Anyone can visit it - no login required unless you've built one into your app. Copy it from **Manage Publishing** (Click **Re-publish** to open, the link is shown in the panel header, with a **Visit** icon and **copy** icons on the side).\n\n\n\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/a1ea2076d7f64114a5161e91a0f3c66c.png\" alt=\"Manage Publishing panel\" caption=\"Manage Publishing panel\" />\n\n\n<Callout type=\"warning\" title=\"Share the live link, not the preview link\">\nYour **preview** URL (it ends in `emergentagent.com`) is for you: it's tied to your working session and the preview **sleeps after ~30 minutes of inactivity**, someone opening it later may find nothing there. Share the `emergent.host` link. The one exception: letting a friend try the app *before* you publish, open the preview in a new tab and share that link while you're both online, knowing it will sleep.\n</Callout>\n\nShare it however you like:\n\n- Text it to friends or family\n- Post it in a group chat or on social media\n- Email it to beta testers\n- Add it to your portfolio\n\nThe link stays the same as long as your app is live, so you can share it once and people can keep visiting. Your live app runs 24/7, visitors don't wait for it to \"wake up.\"\n\n---\n\n## What your visitors see\n\nWhen someone clicks your link, they see the exact version of your app that's currently live - the production environment. This is the polished, stable version you chose to publish (see [Preview vs Published](/preview-vs-deployed-separate) for the difference).\n\nIf you're still iterating in preview, those changes **won't** show up at the public URL until you **Re-publish**. Your live app stays frozen at the last version you published, so it's safe to keep experimenting in the background.\n\n---\n\n## Keep an eye on your live app\n\nEverything you need is in **Manage Publishing** (click **Re-publish** in the top toolbar):\n\n- The panel header shows your app's **Live badge** (green dot), its URL, and a **Visit** button.\n- **View Logs**: each published version in the Publishes section has a View Logs link for what's happening behind the scenes.\n- **Run health check**: the button in the bottom bar checks that your live app is responding properly.\n- **Enable alerts**: a toggle to get notified about publish events.\n- **Analytics**: the Analytics button in the panel header opens App Analytics: traffic for your live app across time ranges from the last 6 hours to the last 30 days. *(Currently available to Pro users.)*\n\nIf your app is crashing or running slowly, see [App slow, crashing or cold-starting](/app-slow-crashing-or-cold-starting) for troubleshooting steps.\n\n---\n\n## Next step: your own web address\n\nSharing `your-app-name.emergent.host` is fine for testers, but if this app represents you or your business, the next upgrade is your own domain, like `myapp.com`. That's the next page: [Use your own web address](/use-your-own-web-address).\n","published_title":"Share it with the world","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"0a5a60c2-b35c-4cdb-89e5-67eeb4a38152","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Get paid","slug":"get-paid","content":"\nYour app can collect payments through Stripe - describe what you want to charge, test with fake money in the built-in sandbox, and switch to real payments when you're ready.\n\n<Callout type=\"success\" title=\"Your revenue is yours\">\nMoney flows **Stripe → your bank**, never through Emergent. **Emergent takes no cut of your sales**, you pay only your Emergent plan/credits, and Stripe charges its own processing fees like it would anywhere.\n</Callout>\n\n---\n\n## The golden rule: test mode first\n\nPayments have **two universes**: test mode (pretend money, fake cards, nothing charges a real bank account) and live mode (real cash). Never go live until you've tested checkout end-to-end with fake cards. One typo in your pricing prompt could charge real customers the wrong amount.\n\n---\n\n## Step 1: Describe what you want to sell\n\nTell your Emergent agent exactly what you're charging for. Be specific:\n\n- \"Add Stripe payment processing. Users should be able to purchase credits for $10, $25, or $50.\"\n- \"Integrate Stripe subscriptions with three tiers: Basic ($9/month), Pro ($29/month), and Enterprise ($99/month).\"\n- \"Add a checkout flow where users can buy individual products from a catalog.\"\n\nThe agent writes all the code - buttons, checkout pages, server logic to confirm payment.\n\n---\n\n## Step 2: The managed sandbox (the default path)\n\nEmergent sets you up with a **managed Stripe sandbox**: the platform manages the\nSTRIPE_* keys for you. They are fetched automatically when you claim the sandbox,\nand you can't (and shouldn't) edit them.\n\n### Make test payments work\n\n<Steps>\n<Step title=\"Open the Payments tab\">\nClick **Manage** (next to **Preview**) and open the **Payments** tab.\n</Step>\n\n<Step title=\"Claim your sandbox\">\nClick **Claim Your Sandbox**.\n</Step>\n\n<Step title=\"Complete Stripe's registration\">\nComplete Stripe's account registration and identity check. This step is skipped\nif you already have a Stripe account.\n</Step>\n\n<Step title=\"Install the Emergent App\">\nWhen you land in the Stripe dashboard, click **Install the Emergent App**.\n</Step>\n</Steps>\n\n<Note>\nThe Payments tab shows your next step at each stage, for example \"Claim your\nStripe sandbox\" or \"Complete your KYC on Stripe\".\n</Note>\n\nGoing live on this path needs **no manual keys at all**: just follow the next\nsteps shown on the Payments tab.\n\n### Prefer your own Stripe account?\n\nThat's the right path if:\n\n- **Different email**: your Stripe account is on a different email.\n- **Country support**: Stripe doesn't support your country (Razorpay and PayPal\n  remain options, see below).\n\nTo switch over:\n\n1. **Unlink the sandbox first**: open the **Payments** tab, click the **3-dots**\n   next to Stripe, and select **Unlink** (owner-only; a dialog explains the\n   consequences). You can also ask the agent to do it.\n2. **Already live?** Your published app keeps its existing keys and keeps\n   transacting. Unlinking only removes the sandbox link.\n3. **Ask the agent to integrate Stripe with your own keys**: test keys go in\n   your project's `.env`, and live keys go in **Preview → Manage → Secrets →\n   Custom keys**.\n\n<Warning>\nNever paste a real key into chat: chat content is sent to the AI provider.\n</Warning>\n---\n\n## Step 3: Test with fake cards\n\nAsk the agent to test:\n\n```\nTest the Stripe checkout flow\n```\n\nThe agent will simulate a purchase. You can also manually click your new Buy button and use [Stripe's test card numbers](https://stripe.com/docs/testing) - like `4242 4242 4242 4242` for a successful charge, or `4000 0000 0000 0002` to trigger a card decline.\n\nWatch what happens: does the success page show up? Does your database record the sale?\n\n---\n\n## Step 4: Switch to real money (when ready)\n\n- **Managed sandbox:** once KYC is complete, going live is handled through the platform.\n- **Your own account:** flip your Stripe dashboard from **Test** to **Live**, copy the live keys (`pk_live_`, `sk_live_`), update them in **Preview → Manage → Secrets → Custom keys**, then click **Re-publish**.\n\nBefore going live, re-read your pricing prompts. A typo like \"$999/month\" instead of \"$9.99/month\" will charge customers real money at the wrong amount.\n\n---\n\n## Outside the US, or on mobile?\n\n- **Regional providers:** depending on your market, other payment integrations are available, for example **Razorpay** for India and **PayPal**. Ask the agent which fits your country and currency.\n- **Mobile (Expo) apps:** Stripe isn't available on mobile-only projects, mobile in-app purchases go through **RevenueCat** (and Razorpay/PayPal remain available). App-store purchases also carry the stores' own fees, see [Monetisation: in-app purchases & subscriptions](/monetisation-in-app-purchases-subscriptions).\n\n---\n\n## When does money reach your bank?\n\nStripe holds funds for a few days (usually 2-7 business days for your first payouts, then 2 days ongoing) before depositing to your bank account. You set up your bank details in the Stripe dashboard under **Settings → Bank accounts and scheduling**.\n\n---\n\n## If something looks wrong\n\n- **Checkout button does nothing**: check the browser console for errors. Your publishable key might be missing or mistyped.\n- **Payments fail in preview with the managed sandbox**: make sure you've **claimed the sandbox and completed KYC**, test payments don't work before that.\n- **Payment succeeds but user doesn't get access**: your webhook might not be set up. Ask the agent: `Set up Stripe webhooks to handle payment confirmation`.\n- **Test card declined in test mode**: make sure you're using a [Stripe test card](https://stripe.com/docs/testing), not a real one.\n\n\n**Go deeper:** [Stripe](/stripe) · [Payment methods & regional billing](/payment-methods-regional-billing)","order":113,"parent_id":null,"icon":"credit-card","description":"Accept payments in your app with Stripe - no code, no finance degree.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.373901+00:00","published_at":"2026-09-24T14:08:37.373901+00:00","published_content":"\nYour app can collect payments through Stripe - describe what you want to charge, test with fake money in the built-in sandbox, and switch to real payments when you're ready.\n\n<Callout type=\"success\" title=\"Your revenue is yours\">\nMoney flows **Stripe → your bank**, never through Emergent. **Emergent takes no cut of your sales**, you pay only your Emergent plan/credits, and Stripe charges its own processing fees like it would anywhere.\n</Callout>\n\n---\n\n## The golden rule: test mode first\n\nPayments have **two universes**: test mode (pretend money, fake cards, nothing charges a real bank account) and live mode (real cash). Never go live until you've tested checkout end-to-end with fake cards. One typo in your pricing prompt could charge real customers the wrong amount.\n\n---\n\n## Step 1: Describe what you want to sell\n\nTell your Emergent agent exactly what you're charging for. Be specific:\n\n- \"Add Stripe payment processing. Users should be able to purchase credits for $10, $25, or $50.\"\n- \"Integrate Stripe subscriptions with three tiers: Basic ($9/month), Pro ($29/month), and Enterprise ($99/month).\"\n- \"Add a checkout flow where users can buy individual products from a catalog.\"\n\nThe agent writes all the code - buttons, checkout pages, server logic to confirm payment.\n\n---\n\n## Step 2: The managed sandbox (the default path)\n\nEmergent sets you up with a **managed Stripe sandbox**: the platform manages the\nSTRIPE_* keys for you. They are fetched automatically when you claim the sandbox,\nand you can't (and shouldn't) edit them.\n\n### Make test payments work\n\n<Steps>\n<Step title=\"Open the Payments tab\">\nClick **Manage** (next to **Preview**) and open the **Payments** tab.\n</Step>\n\n<Step title=\"Claim your sandbox\">\nClick **Claim Your Sandbox**.\n</Step>\n\n<Step title=\"Complete Stripe's registration\">\nComplete Stripe's account registration and identity check. This step is skipped\nif you already have a Stripe account.\n</Step>\n\n<Step title=\"Install the Emergent App\">\nWhen you land in the Stripe dashboard, click **Install the Emergent App**.\n</Step>\n</Steps>\n\n<Note>\nThe Payments tab shows your next step at each stage, for example \"Claim your\nStripe sandbox\" or \"Complete your KYC on Stripe\".\n</Note>\n\nGoing live on this path needs **no manual keys at all**: just follow the next\nsteps shown on the Payments tab.\n\n### Prefer your own Stripe account?\n\nThat's the right path if:\n\n- **Different email**: your Stripe account is on a different email.\n- **Country support**: Stripe doesn't support your country (Razorpay and PayPal\n  remain options, see below).\n\nTo switch over:\n\n1. **Unlink the sandbox first**: open the **Payments** tab, click the **3-dots**\n   next to Stripe, and select **Unlink** (owner-only; a dialog explains the\n   consequences). You can also ask the agent to do it.\n2. **Already live?** Your published app keeps its existing keys and keeps\n   transacting. Unlinking only removes the sandbox link.\n3. **Ask the agent to integrate Stripe with your own keys**: test keys go in\n   your project's `.env`, and live keys go in **Preview → Manage → Secrets →\n   Custom keys**.\n\n<Warning>\nNever paste a real key into chat: chat content is sent to the AI provider.\n</Warning>\n---\n\n## Step 3: Test with fake cards\n\nAsk the agent to test:\n\n```\nTest the Stripe checkout flow\n```\n\nThe agent will simulate a purchase. You can also manually click your new Buy button and use [Stripe's test card numbers](https://stripe.com/docs/testing) - like `4242 4242 4242 4242` for a successful charge, or `4000 0000 0000 0002` to trigger a card decline.\n\nWatch what happens: does the success page show up? Does your database record the sale?\n\n---\n\n## Step 4: Switch to real money (when ready)\n\n- **Managed sandbox:** once KYC is complete, going live is handled through the platform.\n- **Your own account:** flip your Stripe dashboard from **Test** to **Live**, copy the live keys (`pk_live_`, `sk_live_`), update them in **Preview → Manage → Secrets → Custom keys**, then click **Re-publish**.\n\nBefore going live, re-read your pricing prompts. A typo like \"$999/month\" instead of \"$9.99/month\" will charge customers real money at the wrong amount.\n\n---\n\n## Outside the US, or on mobile?\n\n- **Regional providers:** depending on your market, other payment integrations are available, for example **Razorpay** for India and **PayPal**. Ask the agent which fits your country and currency.\n- **Mobile (Expo) apps:** Stripe isn't available on mobile-only projects, mobile in-app purchases go through **RevenueCat** (and Razorpay/PayPal remain available). App-store purchases also carry the stores' own fees, see [Monetisation: in-app purchases & subscriptions](/monetisation-in-app-purchases-subscriptions).\n\n---\n\n## When does money reach your bank?\n\nStripe holds funds for a few days (usually 2-7 business days for your first payouts, then 2 days ongoing) before depositing to your bank account. You set up your bank details in the Stripe dashboard under **Settings → Bank accounts and scheduling**.\n\n---\n\n## If something looks wrong\n\n- **Checkout button does nothing**: check the browser console for errors. Your publishable key might be missing or mistyped.\n- **Payments fail in preview with the managed sandbox**: make sure you've **claimed the sandbox and completed KYC**, test payments don't work before that.\n- **Payment succeeds but user doesn't get access**: your webhook might not be set up. Ask the agent: `Set up Stripe webhooks to handle payment confirmation`.\n- **Test card declined in test mode**: make sure you're using a [Stripe test card](https://stripe.com/docs/testing), not a real one.\n\n\n**Go deeper:** [Stripe](/stripe) · [Payment methods & regional billing](/payment-methods-regional-billing)","published_title":"Get paid","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"05aaf0d8-009a-4f84-9f01-5ec5678d50b2","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Connect your tools","slug":"connect-your-tools","content":"\n\nYou'll learn how to plug external services, like email, payments, and messaging, into your Emergent app so it can send emails, store data, or accept payments without writing connection code yourself.\n\n---\n\n## Two kinds of connections\n\nEmergent connects to other services in two ways:\n\n1. **Integrations with a playbook**: a curated set of services the agent knows deeply. You'll find them as tiles in the **Connectors view** (open your app's **Preview**, click **Manage**, then **Connectors**), each with an **Add** button. The agent follows a tested setup recipe for these. A few playbooks bill a small per-run credit cost, shown with the integration.\n2. **Anything else with a public API**: the agent can wire up services outside the catalog too; you supply the service's API key and the agent writes the connection code. These just don't come with a tested recipe, so expect a bit more iteration.\n\n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/7fafa0c7c2d64c4186964c04c8d594cc.mov\" />\n\n\n\n---\n\n## A few useful integrations\n\nSome of the most common integrations beginners use, grouped by what they help you do:\n\n**Send messages or emails:**\n- **SendGrid** - transactional email delivery (e.g., order confirmations, receipts).\n- **Resend** - another email option *(full-stack web apps only, not available on mobile/Expo projects)*.\n- **Twilio** - SMS, voice calls, and WhatsApp messages.\n- **Slack** - post updates to a Slack workspace.\n\n**Accept payments:**\n- **Stripe** - process credit cards, manage subscriptions, handle billing (see [Get paid](/get-paid), the platform sets up a managed sandbox for you).\n\n\n<Callout type=\"tip\" title=\"Start simple\">\nIf you're building your first app, start with MongoDB (already included) and one messaging or payment integration. You can add more later.\n</Callout>\n\n---\n\n## How to ask the agent to connect a tool\n\nYou don't need to configure integrations manually, just describe what you want in chat and the agent will guide you.\n\n<Steps>\n<Step title=\"Describe the task in plain English\">\nFor example:\n\n- *\"I need to send an email when someone signs up.\"*\n- *\"Let users pay with Stripe.\"*\n- *\"Pull data from this Google Sheet every hour.\"*\n</Step>\n\n<Step title=\"The agent sets up the key names, you supply the values\">\nIf the service requires an API key (most do), the agent adds the key **name** to your app's `.env`. Put the real **value** in yourself: for your live app, in **Preview → Manage → Secrets → Custom keys**, and never paste a real key into chat. Full walkthrough in [Keep it safe](/keep-it-safe).\n</Step>\n\n<Step title=\"The agent writes the code\">\nOnce the credentials are in place, the agent generates the connection code, connecting to the service, calling the right endpoints, and handling errors.\n</Step>\n</Steps>\n\n<Callout type=\"note\" title=\"Where to find API keys\">\nMost services provide API keys in their developer or settings dashboard. The agent will tell you exactly where to look for each service (e.g., \"Get your SendGrid key from Settings → API Keys\").\n</Callout>\n\n---\n\n## If you're not sure which integration to use\n\nIf you know *what* you want to do but not *which* service to use, just ask the agent:\n\n- *\"How do I send emails from my app?\"* → The agent will suggest SendGrid or another email provider.\n- *\"I need to accept payments.\"* → The agent will recommend Stripe or PayPal and explain the difference.\n- *\"Where should I store user profiles?\"* → The agent will suggest MongoDB (already included) or another database.\n\nThe agent knows which integrations are available on Emergent and will guide you to the right one.\n\n\n**Go deeper:** [Key integrations catalogue](/key-integrations-catalogue)","order":114,"parent_id":null,"icon":"plug","description":"Plug in Gmail, Sheets, Slack, and more so your app works with what you use.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-10-05T14:28:17.839263+00:00","published_at":"2026-10-05T14:28:17.839263+00:00","published_content":"\n\nYou'll learn how to plug external services, like email, payments, and messaging, into your Emergent app so it can send emails, store data, or accept payments without writing connection code yourself.\n\n---\n\n## Two kinds of connections\n\nEmergent connects to other services in two ways:\n\n1. **Integrations with a playbook**: a curated set of services the agent knows deeply. You'll find them as tiles in the **Connectors view** (open your app's **Preview**, click **Manage**, then **Connectors**), each with an **Add** button. The agent follows a tested setup recipe for these. A few playbooks bill a small per-run credit cost, shown with the integration.\n2. **Anything else with a public API**: the agent can wire up services outside the catalog too; you supply the service's API key and the agent writes the connection code. These just don't come with a tested recipe, so expect a bit more iteration.\n\n\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/7fafa0c7c2d64c4186964c04c8d594cc.mov\" />\n\n\n\n---\n\n## A few useful integrations\n\nSome of the most common integrations beginners use, grouped by what they help you do:\n\n**Send messages or emails:**\n- **SendGrid** - transactional email delivery (e.g., order confirmations, receipts).\n- **Resend** - another email option *(full-stack web apps only, not available on mobile/Expo projects)*.\n- **Twilio** - SMS, voice calls, and WhatsApp messages.\n- **Slack** - post updates to a Slack workspace.\n\n**Accept payments:**\n- **Stripe** - process credit cards, manage subscriptions, handle billing (see [Get paid](/get-paid), the platform sets up a managed sandbox for you).\n\n\n<Callout type=\"tip\" title=\"Start simple\">\nIf you're building your first app, start with MongoDB (already included) and one messaging or payment integration. You can add more later.\n</Callout>\n\n---\n\n## How to ask the agent to connect a tool\n\nYou don't need to configure integrations manually, just describe what you want in chat and the agent will guide you.\n\n<Steps>\n<Step title=\"Describe the task in plain English\">\nFor example:\n\n- *\"I need to send an email when someone signs up.\"*\n- *\"Let users pay with Stripe.\"*\n- *\"Pull data from this Google Sheet every hour.\"*\n</Step>\n\n<Step title=\"The agent sets up the key names, you supply the values\">\nIf the service requires an API key (most do), the agent adds the key **name** to your app's `.env`. Put the real **value** in yourself: for your live app, in **Preview → Manage → Secrets → Custom keys**, and never paste a real key into chat. Full walkthrough in [Keep it safe](/keep-it-safe).\n</Step>\n\n<Step title=\"The agent writes the code\">\nOnce the credentials are in place, the agent generates the connection code, connecting to the service, calling the right endpoints, and handling errors.\n</Step>\n</Steps>\n\n<Callout type=\"note\" title=\"Where to find API keys\">\nMost services provide API keys in their developer or settings dashboard. The agent will tell you exactly where to look for each service (e.g., \"Get your SendGrid key from Settings → API Keys\").\n</Callout>\n\n---\n\n## If you're not sure which integration to use\n\nIf you know *what* you want to do but not *which* service to use, just ask the agent:\n\n- *\"How do I send emails from my app?\"* → The agent will suggest SendGrid or another email provider.\n- *\"I need to accept payments.\"* → The agent will recommend Stripe or PayPal and explain the difference.\n- *\"Where should I store user profiles?\"* → The agent will suggest MongoDB (already included) or another database.\n\nThe agent knows which integrations are available on Emergent and will guide you to the right one.\n\n\n**Go deeper:** [Key integrations catalogue](/key-integrations-catalogue)","published_title":"Connect your tools","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"81a71fb5-13c8-4b0e-8411-f2367cd3b886","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Use your own web address","slug":"use-your-own-web-address","content":"\nYour app starts with a free `yourappname.emergent.host` address. A custom domain replaces that with your own name - like `myapp.com` - so visitors see your brand in the address bar.\n\n* * *\n\n## Buying vs bringing your own\n\nYou have two paths:\n\n- **Already own a domain?** (e.g., you bought `myapp.com` from Namecheap or GoDaddy) Skip ahead to the connection steps below.\n- **Need to buy one?** Head to any domain registrar - Namecheap, Google Domains, Cloudflare - search for your name, and check out. You'll manage DNS records in the next step at that same site. Emergent also provides the option for you to buy domains on the platform itself.(**Preview → Manage → Domain**→**Buy your domain**)\n\nDNS is the internet phonebook - it tells browsers which server hosts your domain. An **A record** is one line in that phonebook: \"this name points to this server address.\" Updating DNS records can take a few minutes to a couple of hours to reach everyone, so don't panic if your domain doesn't work instantly.\n\n* * *\n\n## Connect your domain\n\nThe recommended method is **Auto-Link**, which configures your DNS automatically. If you prefer to set records manually, follow the steps below.\n\nIn your Emergent workspace, go to **Preview → Manage → Domain** and find **Link your domain here** → add your domain there and click **Link manually** (click **Auto-Link** here instead if you want automatic linking). The panel will show you two shared A record values. Log in to your domain registrar (wherever you bought the domain). Find the DNS settings page and create **two A records**:\n\n**First A record:**\n\n- **Host / Name**: `@` (or leave blank)\n- **Type**: `A`\n- **Value**: `162.159.142.117`\n- **TTL**: `Auto` or `3600`\n\n**Second A record:**\n\n- **Host / Name**: `@` (or leave blank)\n- **Type**: `A`\n- **Value**: `172.66.2.113`\n- **TTL**: `Auto` or `3600`\n\nSave the records.\n\nMost visitors type `www.myapp.com`. Create a **CNAME record** so both versions work:\n\n- **Host / Name**: `www`\n- **Type**: `CNAME`\n- **Value**: `myapp.com` (your root domain, no `http://`)\n- **TTL**: `Auto` or `3600`\n\nSave this record too.\n\nBack in the Domain panel on Emergent, enter your domain (e.g., `myapp.com`) and click **Check Status**. Emergent checks for the A records and will set up an SSL certificate automatically - usually within a few minutes, occasionally up to 24 hours if DNS is slow. After DNS propagates, `https://myapp.com` and `https://www.myapp.com` will both load your app. Emergent automatically redirects one to the other so you don't end up with duplicate content.\n\n> **Note for Cloudflare users:** If your DNS is managed on Cloudflare, ensure your A records remain set to **DNS-only (gray cloud)** permanently. Enabling the orange cloud (proxy) will cause Error 1014.\n\n<Callout type=\"warning\" title=\"If you ever take the app offline\">\nShutting down a live app **removes the custom-domain link**, and it is not restored automatically when you publish again, you'll re-add the domain here in the Domain tab. See the **Taking your app offline** section of [Put your app live](/put-your-app-live).\n</Callout>\n\n* * *\n\n## If your domain won't load\n\n**Check your DNS records** - Use a tool like [dnschecker.org](https://dnschecker.org) to confirm both A records point to the Emergent shared IPs and the CNAME points to your root domain. Fix any typos at your registrar.\n\n**Wait a bit longer** - DNS can take 1-2 hours (rarely up to 48 hours) to update everywhere. Check again in an incognito window to rule out browser caching.\n\n**Look at the status badge** - In **Preview → Manage → Domain**, click the refresh status icon. Your custom domain row shows **Pending**, **Linked**, or **Failed**. If it shows **Failed**, review your DNS records for any mismatch.\n\n**Clear your local cache** - Your computer remembers old DNS lookups. On Windows run `ipconfig /flushdns` in Command Prompt; on macOS run `sudo dscacheutil -flushcache` in Terminal.\n\nEvery DNS provider's dashboard looks different. If you can't find the A record or CNAME section, search \"[your registrar name] add DNS record\" - most have a step-by-step guide.\n\n\n**Go deeper:** [Custom domain](/custom-domain)","order":115,"parent_id":null,"icon":"globe","description":"Turn a default app address into your own custom domain.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.383835+00:00","published_at":"2026-09-24T14:08:37.383835+00:00","published_content":"\nYour app starts with a free `yourappname.emergent.host` address. A custom domain replaces that with your own name - like `myapp.com` - so visitors see your brand in the address bar.\n\n* * *\n\n## Buying vs bringing your own\n\nYou have two paths:\n\n- **Already own a domain?** (e.g., you bought `myapp.com` from Namecheap or GoDaddy) Skip ahead to the connection steps below.\n- **Need to buy one?** Head to any domain registrar - Namecheap, Google Domains, Cloudflare - search for your name, and check out. You'll manage DNS records in the next step at that same site. Emergent also provides the option for you to buy domains on the platform itself.(**Preview → Manage → Domain**→**Buy your domain**)\n\nDNS is the internet phonebook - it tells browsers which server hosts your domain. An **A record** is one line in that phonebook: \"this name points to this server address.\" Updating DNS records can take a few minutes to a couple of hours to reach everyone, so don't panic if your domain doesn't work instantly.\n\n* * *\n\n## Connect your domain\n\nThe recommended method is **Auto-Link**, which configures your DNS automatically. If you prefer to set records manually, follow the steps below.\n\nIn your Emergent workspace, go to **Preview → Manage → Domain** and find **Link your domain here** → add your domain there and click **Link manually** (click **Auto-Link** here instead if you want automatic linking). The panel will show you two shared A record values. Log in to your domain registrar (wherever you bought the domain). Find the DNS settings page and create **two A records**:\n\n**First A record:**\n\n- **Host / Name**: `@` (or leave blank)\n- **Type**: `A`\n- **Value**: `162.159.142.117`\n- **TTL**: `Auto` or `3600`\n\n**Second A record:**\n\n- **Host / Name**: `@` (or leave blank)\n- **Type**: `A`\n- **Value**: `172.66.2.113`\n- **TTL**: `Auto` or `3600`\n\nSave the records.\n\nMost visitors type `www.myapp.com`. Create a **CNAME record** so both versions work:\n\n- **Host / Name**: `www`\n- **Type**: `CNAME`\n- **Value**: `myapp.com` (your root domain, no `http://`)\n- **TTL**: `Auto` or `3600`\n\nSave this record too.\n\nBack in the Domain panel on Emergent, enter your domain (e.g., `myapp.com`) and click **Check Status**. Emergent checks for the A records and will set up an SSL certificate automatically - usually within a few minutes, occasionally up to 24 hours if DNS is slow. After DNS propagates, `https://myapp.com` and `https://www.myapp.com` will both load your app. Emergent automatically redirects one to the other so you don't end up with duplicate content.\n\n> **Note for Cloudflare users:** If your DNS is managed on Cloudflare, ensure your A records remain set to **DNS-only (gray cloud)** permanently. Enabling the orange cloud (proxy) will cause Error 1014.\n\n<Callout type=\"warning\" title=\"If you ever take the app offline\">\nShutting down a live app **removes the custom-domain link**, and it is not restored automatically when you publish again, you'll re-add the domain here in the Domain tab. See the **Taking your app offline** section of [Put your app live](/put-your-app-live).\n</Callout>\n\n* * *\n\n## If your domain won't load\n\n**Check your DNS records** - Use a tool like [dnschecker.org](https://dnschecker.org) to confirm both A records point to the Emergent shared IPs and the CNAME points to your root domain. Fix any typos at your registrar.\n\n**Wait a bit longer** - DNS can take 1-2 hours (rarely up to 48 hours) to update everywhere. Check again in an incognito window to rule out browser caching.\n\n**Look at the status badge** - In **Preview → Manage → Domain**, click the refresh status icon. Your custom domain row shows **Pending**, **Linked**, or **Failed**. If it shows **Failed**, review your DNS records for any mismatch.\n\n**Clear your local cache** - Your computer remembers old DNS lookups. On Windows run `ipconfig /flushdns` in Command Prompt; on macOS run `sudo dscacheutil -flushcache` in Terminal.\n\nEvery DNS provider's dashboard looks different. If you can't find the A record or CNAME section, search \"[your registrar name] add DNS record\" - most have a step-by-step guide.\n\n\n**Go deeper:** [Custom domain](/custom-domain)","published_title":"Use your own web address","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"fa4ac03c-9157-45f5-bc0a-86da9e0c2d96","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Get found on Google","slug":"get-found-on-google","content":"\nOnce you make your app live, you'll want people to actually find it. This guide covers the basics of search engine optimization (SEO).\n\n## What SEO is (and why it matters)\n\nSEO stands for \"search engine optimization\", the practice of making your app easier for Google and other search engines to understand and show to searchers. When done right, someone searching for what your app does can discover it organically, without you paying for ads.\n\n## Optimizing your app for search\n\nSearch engines look at your page titles, descriptions, and content to decide what your app is about. Clear, descriptive text helps both people and Google understand what you've built.\n\n<Callout type=\"note\" title=\"Help search engines read your app\">\nEmergent apps draw their pages with JavaScript, which search engines can struggle to read. The Enable SEO toggle fixes this, for a standard app you want indexed, turn it ON: click Re-publish → Manage Publishing → Domain tab → Enable SEO. It takes effect in about a minute. If your app is private or you run your own server-side rendering, leave it off.\n</Callout>\n\n**How it works, how to verify it, and its limitations:** see [Enable SEO: crawler pre-rendering](/enable-seo-crawler-pre-rendering).\n\n## Verifying with Google Search Console\n\nGoogle Search Console is a free tool that shows you how your site appears in search results and flags any issues Google encounters when crawling your pages.\n\n## Setting realistic expectations\n\nSEO takes time. Google typically needs a few weeks (sometimes longer) to discover your site, understand it, and start ranking it for relevant searches. You will not see traffic overnight, and that is completely normal, even for large companies launching new pages.\n\n<Callout type=\"tip\" title=\"Patience pays off\">\nFocus on building something genuinely useful. Quality content and a good experience for people using your app are the best long-term SEO strategies.\n</Callout>\n","order":116,"parent_id":null,"icon":"search","description":"Help people discover your app when they search.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.250223+00:00","published_at":"2026-09-24T14:08:37.250223+00:00","published_content":"\nOnce you make your app live, you'll want people to actually find it. This guide covers the basics of search engine optimization (SEO).\n\n## What SEO is (and why it matters)\n\nSEO stands for \"search engine optimization\", the practice of making your app easier for Google and other search engines to understand and show to searchers. When done right, someone searching for what your app does can discover it organically, without you paying for ads.\n\n## Optimizing your app for search\n\nSearch engines look at your page titles, descriptions, and content to decide what your app is about. Clear, descriptive text helps both people and Google understand what you've built.\n\n<Callout type=\"note\" title=\"Help search engines read your app\">\nEmergent apps draw their pages with JavaScript, which search engines can struggle to read. The Enable SEO toggle fixes this, for a standard app you want indexed, turn it ON: click Re-publish → Manage Publishing → Domain tab → Enable SEO. It takes effect in about a minute. If your app is private or you run your own server-side rendering, leave it off.\n</Callout>\n\n**How it works, how to verify it, and its limitations:** see [Enable SEO: crawler pre-rendering](/enable-seo-crawler-pre-rendering).\n\n## Verifying with Google Search Console\n\nGoogle Search Console is a free tool that shows you how your site appears in search results and flags any issues Google encounters when crawling your pages.\n\n## Setting realistic expectations\n\nSEO takes time. Google typically needs a few weeks (sometimes longer) to discover your site, understand it, and start ranking it for relevant searches. You will not see traffic overnight, and that is completely normal, even for large companies launching new pages.\n\n<Callout type=\"tip\" title=\"Patience pays off\">\nFocus on building something genuinely useful. Quality content and a good experience for people using your app are the best long-term SEO strategies.\n</Callout>\n","published_title":"Get found on Google","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"26df5a9a-cabb-495d-9bbf-1ebbbff809a1","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Keep it safe","slug":"keep-it-safe","content":"\nA quick checklist to keep your users' information safe - where secrets actually live on Emergent, what your AI agent can see, and how to protect data before you publish.\n\n---\n\n## Where secrets live: `.env` in preview, Secrets in production\n\nOn Emergent, \"environment variables\" and \"secrets\" are the same thing: key-value pairs like `STRIPE_KEY=sk_…` that your app reads at runtime. They live in **two separate places**:\n\n- **Preview**: secrets live in `.env` files inside your project's code. The agent manages these: to add a new key, **ask the agent in chat to add it to `.env`** (give the key a name; put the real value in yourself afterwards, see the warning below).\n- **Production (your live app)**: secrets live in the **Secrets tab** (click **Preview**, then **Manage**). There you'll see **System keys** (platform-managed, like your database connection, don't touch) and **Custom keys** (yours).\n\nHow the two connect: on your **first Publish**, the values in your `.env` files carry over to production. **After that, the two sets are separate**, changing a preview value does not change production. To update a live value: **Preview → Manage → Secrets** → edit the Custom key → **Save and re-publish**. New keys can't be created from the Secrets panel, they're added via the agent in `.env`, then picked up on the next Re-publish.\n\n<Callout type=\"warning\" title=\"Never paste a real secret in chat\">\nAnything you type in chat is sent to the AI provider. So: have the agent create the key **name** in `.env`, then put the real **value** in yourself, in the **Secrets tab** (**Preview → Manage → Secrets → Custom keys** → Save and republish) for your live app. If you already pasted a secret in chat, rotate that key with your provider.\n</Callout>\n\n<Callout type=\"note\" title=\"Who can see the values\">\nSecret values are masked in the panel by default, but they can be revealed and copied by **anyone with publish access** to your project. Treat project access as secret access.\n</Callout>\n\n---\n\n## What the AI sees (and doesn't see)\n\nYour agent needs context to build your app, but Emergent keeps sensitive data out of its view:\n\n| What the agent sees | What it never sees |\n|---------------------|-------------------|\n| Your code files (including `.env` in preview) | Secret values from the Secrets tab (production) |\n| Your database's structure (table names, field types) | Actual database records (unless you paste them) |\n| Secret key *names* | Production secret *values* |\n| Your prompts and chat history | Other users' projects |\n\n<Callout type=\"success\" title=\"Your data is private by default\">\nYour projects, chat logs, code, and secrets are never shared with other users, and your personal data is never used to train AI models (DPA 12.1). Emergent isolates every workspace, encrypts your data in transit, and encrypts your secrets at rest.\n</Callout>\n\nAI providers (OpenAI, Anthropic, etc.) process your prompts and code to respond, but - per their enterprise terms - they do not train public models on API traffic from commercial use.\n\n---\n\n## Add login if users need private data\n\nOnce your app is live, **anyone with the URL can visit it**. If each person should only see their own orders, messages, or profile, you need user accounts and authentication.\n\n<Tip>\nSee [Add login & user accounts](/add-login-user-accounts) for a step-by-step guide to adding sign-in flows and protecting private data behind login screens.\n</Tip>\n\nWithout login, all data in your app is visible to anyone who finds the link - so plan access control before you share your app publicly.\n\n---\n\n## Pre-launch safety checklist\n\nBefore you show your app to real users, run through these quick checks:\n\n- **Secrets in `.env` / the Secrets tab?** - No API keys or passwords hard-coded in source files, and none ever pasted in chat.\n- **Production values set?** - After your first Publish, check **Preview → Manage → Secrets** and confirm your Custom keys carry the right live values (test keys swapped for live ones where that applies).\n- **Login tested?** - If your app has user accounts, sign in as a test user and confirm they can't see another user's data.\n- **Public URL reminder** - Your live app is accessible to anyone with the link. If that's not what you want, add authentication or take the app offline.\n\n<Callout type=\"note\" title=\"Live apps are public by URL\">\nDo **not** hard-code sensitive data in client-side JavaScript or HTML - use secrets and server-side logic to protect them.\n</Callout>\n\n---\n\n## If something looks wrong\n\nIf you accidentally pasted a secret value in chat, add the key properly (agent → `.env`, value via the Secrets tab), then **rotate** that key with your provider so the old one can't be used.\n\nIf you suspect a data leak or access issue, contact [support@emergent.sh](mailto:support@emergent.sh) - the team can help audit logs and lock down your workspace.\n\n\n**Go deeper:** [Secrets & env variables](/secrets-env-variables)","order":117,"parent_id":null,"icon":"shield","description":"Simple checks so your users' data stays protected.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.367855+00:00","published_at":"2026-09-24T14:08:37.367855+00:00","published_content":"\nA quick checklist to keep your users' information safe - where secrets actually live on Emergent, what your AI agent can see, and how to protect data before you publish.\n\n---\n\n## Where secrets live: `.env` in preview, Secrets in production\n\nOn Emergent, \"environment variables\" and \"secrets\" are the same thing: key-value pairs like `STRIPE_KEY=sk_…` that your app reads at runtime. They live in **two separate places**:\n\n- **Preview**: secrets live in `.env` files inside your project's code. The agent manages these: to add a new key, **ask the agent in chat to add it to `.env`** (give the key a name; put the real value in yourself afterwards, see the warning below).\n- **Production (your live app)**: secrets live in the **Secrets tab** (click **Preview**, then **Manage**). There you'll see **System keys** (platform-managed, like your database connection, don't touch) and **Custom keys** (yours).\n\nHow the two connect: on your **first Publish**, the values in your `.env` files carry over to production. **After that, the two sets are separate**, changing a preview value does not change production. To update a live value: **Preview → Manage → Secrets** → edit the Custom key → **Save and re-publish**. New keys can't be created from the Secrets panel, they're added via the agent in `.env`, then picked up on the next Re-publish.\n\n<Callout type=\"warning\" title=\"Never paste a real secret in chat\">\nAnything you type in chat is sent to the AI provider. So: have the agent create the key **name** in `.env`, then put the real **value** in yourself, in the **Secrets tab** (**Preview → Manage → Secrets → Custom keys** → Save and republish) for your live app. If you already pasted a secret in chat, rotate that key with your provider.\n</Callout>\n\n<Callout type=\"note\" title=\"Who can see the values\">\nSecret values are masked in the panel by default, but they can be revealed and copied by **anyone with publish access** to your project. Treat project access as secret access.\n</Callout>\n\n---\n\n## What the AI sees (and doesn't see)\n\nYour agent needs context to build your app, but Emergent keeps sensitive data out of its view:\n\n| What the agent sees | What it never sees |\n|---------------------|-------------------|\n| Your code files (including `.env` in preview) | Secret values from the Secrets tab (production) |\n| Your database's structure (table names, field types) | Actual database records (unless you paste them) |\n| Secret key *names* | Production secret *values* |\n| Your prompts and chat history | Other users' projects |\n\n<Callout type=\"success\" title=\"Your data is private by default\">\nYour projects, chat logs, code, and secrets are never shared with other users, and your personal data is never used to train AI models (DPA 12.1). Emergent isolates every workspace, encrypts your data in transit, and encrypts your secrets at rest.\n</Callout>\n\nAI providers (OpenAI, Anthropic, etc.) process your prompts and code to respond, but - per their enterprise terms - they do not train public models on API traffic from commercial use.\n\n---\n\n## Add login if users need private data\n\nOnce your app is live, **anyone with the URL can visit it**. If each person should only see their own orders, messages, or profile, you need user accounts and authentication.\n\n<Tip>\nSee [Add login & user accounts](/add-login-user-accounts) for a step-by-step guide to adding sign-in flows and protecting private data behind login screens.\n</Tip>\n\nWithout login, all data in your app is visible to anyone who finds the link - so plan access control before you share your app publicly.\n\n---\n\n## Pre-launch safety checklist\n\nBefore you show your app to real users, run through these quick checks:\n\n- **Secrets in `.env` / the Secrets tab?** - No API keys or passwords hard-coded in source files, and none ever pasted in chat.\n- **Production values set?** - After your first Publish, check **Preview → Manage → Secrets** and confirm your Custom keys carry the right live values (test keys swapped for live ones where that applies).\n- **Login tested?** - If your app has user accounts, sign in as a test user and confirm they can't see another user's data.\n- **Public URL reminder** - Your live app is accessible to anyone with the link. If that's not what you want, add authentication or take the app offline.\n\n<Callout type=\"note\" title=\"Live apps are public by URL\">\nDo **not** hard-code sensitive data in client-side JavaScript or HTML - use secrets and server-side logic to protect them.\n</Callout>\n\n---\n\n## If something looks wrong\n\nIf you accidentally pasted a secret value in chat, add the key properly (agent → `.env`, value via the Secrets tab), then **rotate** that key with your provider so the old one can't be used.\n\nIf you suspect a data leak or access issue, contact [support@emergent.sh](mailto:support@emergent.sh) - the team can help audit logs and lock down your workspace.\n\n\n**Go deeper:** [Secrets & env variables](/secrets-env-variables)","published_title":"Keep it safe","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"bdc69bd5-5f81-4de6-a901-562ab544127b","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Write prompts that work","slug":"write-prompts-that-work","content":"\nLearn how to adjust your wording to get dramatically better results from the agent - without needing to know any code.\n\n## The anatomy of a strong prompt\n\nA strong first prompt includes four elements (from the [Your first build](/start-with-your-idea) guide):\n\n1. **Purpose** - what the app does in one sentence\n2. **Core features** - 3-5 bullet points of what users can do\n3. **Design hint** - visual style or mood (e.g. \"clean and minimal,\" \"warm and colorful\")\n4. **How it should feel** - the experience of using it (e.g. \"fast data entry,\" \"one-tap actions\")\n\nYou don't need to specify tech stack, database, or file structure - the agent handles those details. Focus on *what* the app should do and *how* it should feel.\n\n<Callout type=\"note\" title=\"The golden rule: clarity, not brevity\">\nYou can ask for **several things in one prompt**, the agent handles that fine, as long as each is unmistakably clear: what to change, where it is, what the end state should be. Number them. What breaks iteration is vagueness, not volume. (Same rule as in [Make it yours](/make-it-yours).)\n</Callout>\n\n## Start rough, shape it in Plan mode\n\nYou don't need a perfect request to begin. Switch the composer's **Build / Plan switcher** to **Plan** (or press **⌥P**) and send your rough idea. The agent responds with a **plan proposal card**, with two options: **Request changes** or **Looks good, let's build it**. Plan mode has the full context of your app, so it shapes a better plan than trying to write the whole request in one shot. Nothing is built until you approve.\n\nPlan mode is unavailable in Brainstorm, and E3 sessions.\n\n<Tip title=\"Small wording changes matter\">\nCompare \"add a rating\" with \"add a 5-star rating with half-star increments.\" The second gives the agent a clearer target and saves you back-and-forth refinement.\n</Tip>\n\n**Ready-made starter prompts**\n\nHere are a few examples you can copy and adapt:\n\n**Simple booking app:**\n> \"Build an appointment booking app. Users can see available time slots for the next two weeks, book a slot with their name and email, and get a confirmation. Use a calendar view that feels clean and minimal.\"\n\n**Small online store:**\n> \"Create a small store where I can list products with photos, prices, and descriptions. Customers can add items to a cart and check out (no payment for now - just collect their info). Keep the design warm and colorful, with big product images.\"\n\n**Personal portfolio:**\n> \"Make a portfolio site where I can show my projects. Each project has a title, image, description, and link. Include an about-me page and a contact form. The design should feel clean and professional, easy to skim.\"\n\n## Before and after: fixing vs adding\n\nWhen something doesn't work the way you want, describe the problem clearly rather than guessing at a solution.\n\n**Instead of:**\n> \"Change the button color to blue\"\n\n**Try:**\n> \"The submit button on the bottom right is hard to see against the background. Make it stand out more.\"\n\nThis gives the agent room to fix the root issue (contrast) rather than just applying your guess (blue might not solve it).\n\n**Instead of:**\n> \"Add a filter dropdown\"\n\n**Try:**\n> \"Let me filter books by read/unread status. A toggle or tabs would work.\"\n\nThe second version states the goal and suggests patterns for how your app looks and feels, but doesn't lock the agent into one approach.\n\n## Use specific examples\n\nWhen you want a particular behavior, show a real example.\n\n**Vague:**\n> \"Make the form easier to use\"\n\n**Specific:**\n> \"Right now I have to tap five fields to add a book. Can we use a floating action button that opens an inline form, like in the Google Keep app?\"\n\nThe agent can infer patterns from familiar reference points (app names, conventions for how apps look and feel, or even \"like how Stripe does checkout\").\n\n## Keep long projects on the rails\n\nTwo habits that prevent the agent from re-breaking earlier work on a long-running app:\n\n- **Ask the agent to maintain a changelog** of features and fixes built so far, it gives the agent a reliable record of what it has already done as the conversation grows.\n- **Scope big cleanups down.** Broad prompts like \"clean up / reorganize everything\" invite sweeping changes and regressions. For refactors, ask for targeted, incremental edits, and consider [forking first](/checkpoints-undo-anything) as a safety net.\n\n## If something looks wrong\n\nIf the agent misunderstands your prompt, reply with clarification in the same chat thread. You don't need to start over - just say \"Actually, I meant...\" and describe the gap.\n\nThe agent keeps context from earlier messages, so follow-up corrections are faster than rewriting the entire prompt.\n","order":118,"parent_id":null,"icon":"pencil","description":"Small wording changes, dramatically better results.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.356427+00:00","published_at":"2026-09-24T14:08:37.356427+00:00","published_content":"\nLearn how to adjust your wording to get dramatically better results from the agent - without needing to know any code.\n\n## The anatomy of a strong prompt\n\nA strong first prompt includes four elements (from the [Your first build](/start-with-your-idea) guide):\n\n1. **Purpose** - what the app does in one sentence\n2. **Core features** - 3-5 bullet points of what users can do\n3. **Design hint** - visual style or mood (e.g. \"clean and minimal,\" \"warm and colorful\")\n4. **How it should feel** - the experience of using it (e.g. \"fast data entry,\" \"one-tap actions\")\n\nYou don't need to specify tech stack, database, or file structure - the agent handles those details. Focus on *what* the app should do and *how* it should feel.\n\n<Callout type=\"note\" title=\"The golden rule: clarity, not brevity\">\nYou can ask for **several things in one prompt**, the agent handles that fine, as long as each is unmistakably clear: what to change, where it is, what the end state should be. Number them. What breaks iteration is vagueness, not volume. (Same rule as in [Make it yours](/make-it-yours).)\n</Callout>\n\n## Start rough, shape it in Plan mode\n\nYou don't need a perfect request to begin. Switch the composer's **Build / Plan switcher** to **Plan** (or press **⌥P**) and send your rough idea. The agent responds with a **plan proposal card**, with two options: **Request changes** or **Looks good, let's build it**. Plan mode has the full context of your app, so it shapes a better plan than trying to write the whole request in one shot. Nothing is built until you approve.\n\nPlan mode is unavailable in Brainstorm, and E3 sessions.\n\n<Tip title=\"Small wording changes matter\">\nCompare \"add a rating\" with \"add a 5-star rating with half-star increments.\" The second gives the agent a clearer target and saves you back-and-forth refinement.\n</Tip>\n\n**Ready-made starter prompts**\n\nHere are a few examples you can copy and adapt:\n\n**Simple booking app:**\n> \"Build an appointment booking app. Users can see available time slots for the next two weeks, book a slot with their name and email, and get a confirmation. Use a calendar view that feels clean and minimal.\"\n\n**Small online store:**\n> \"Create a small store where I can list products with photos, prices, and descriptions. Customers can add items to a cart and check out (no payment for now - just collect their info). Keep the design warm and colorful, with big product images.\"\n\n**Personal portfolio:**\n> \"Make a portfolio site where I can show my projects. Each project has a title, image, description, and link. Include an about-me page and a contact form. The design should feel clean and professional, easy to skim.\"\n\n## Before and after: fixing vs adding\n\nWhen something doesn't work the way you want, describe the problem clearly rather than guessing at a solution.\n\n**Instead of:**\n> \"Change the button color to blue\"\n\n**Try:**\n> \"The submit button on the bottom right is hard to see against the background. Make it stand out more.\"\n\nThis gives the agent room to fix the root issue (contrast) rather than just applying your guess (blue might not solve it).\n\n**Instead of:**\n> \"Add a filter dropdown\"\n\n**Try:**\n> \"Let me filter books by read/unread status. A toggle or tabs would work.\"\n\nThe second version states the goal and suggests patterns for how your app looks and feels, but doesn't lock the agent into one approach.\n\n## Use specific examples\n\nWhen you want a particular behavior, show a real example.\n\n**Vague:**\n> \"Make the form easier to use\"\n\n**Specific:**\n> \"Right now I have to tap five fields to add a book. Can we use a floating action button that opens an inline form, like in the Google Keep app?\"\n\nThe agent can infer patterns from familiar reference points (app names, conventions for how apps look and feel, or even \"like how Stripe does checkout\").\n\n## Keep long projects on the rails\n\nTwo habits that prevent the agent from re-breaking earlier work on a long-running app:\n\n- **Ask the agent to maintain a changelog** of features and fixes built so far, it gives the agent a reliable record of what it has already done as the conversation grows.\n- **Scope big cleanups down.** Broad prompts like \"clean up / reorganize everything\" invite sweeping changes and regressions. For refactors, ask for targeted, incremental edits, and consider [forking first](/checkpoints-undo-anything) as a safety net.\n\n## If something looks wrong\n\nIf the agent misunderstands your prompt, reply with clarification in the same chat thread. You don't need to start over - just say \"Actually, I meant...\" and describe the gap.\n\nThe agent keeps context from earlier messages, so follow-up corrections are faster than rewriting the entire prompt.\n","published_title":"Write prompts that work","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"5ae62b08-2389-464e-bde8-acaf1a48fe9c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"When something breaks","slug":"when-something-breaks","content":"\nA calm path for when your app has errors or doesn't look right: how to report a bug so it gets fixed in one round, how to tell *what kind* of problem you're looking at, and what to send support if you're stuck.\n\n## First: which of these is it?\n\nMost \"something broke\" moments are one of four situations, each with a different fix:\n\n| What you're seeing | What it usually is | What to do |\n|---|---|---|\n| Works in preview, broken on the live app | A **configuration difference** between the two environments, not the code | Check **Preview → Manage → Secrets**, production values are separate from preview. See [Works in preview but breaks in production](/works-in-preview-but-breaks-in-production) |\n| The agent repeats the same failing fix over and over | A **loop** (\"doom loop\") | Don't keep re-asking the same way. Pause it, describe what went wrong and what to do *differently*, or **fork** to give it a fresh start (see below) |\n| The agent stopped mid-job | A **stop reason**, often normal | See the stop-reasons list below |\n| A feature that worked yesterday is broken after new changes | A **regression** | **Roll back** to the last good point in the chat timeline (see [Checkpoints: undo anything](/checkpoints-undo-anything)), then re-request the new change more narrowly |\n\n<Callout type=\"note\" title=\"What 'verified' means\">\nWhen the agent says it **verified** a fix, that means it confirmed the fix works **in preview**, the agent has no access to your live app. If it works in preview, it should work live too *unless the two environments are configured differently*, which is why the first row above is so common.\n</Callout>\n\n## If you see an error message\n\n<Steps>\n<Step title=\"Copy the entire error\">\nWhen something breaks, grab the **full error text** from your browser console or the error modal - including stack traces, file paths, and line numbers. Paste it straight into the chat with a short note:\n\n```\nplease solve this error\n\n[paste the complete error here]\n```\n\nThe agent will read the stack trace, find the broken component or connection, and push a fix.\n</Step>\n\n<Step title=\"Add a screenshot for visual bugs\">\nIf the problem is visual - a button hidden off-screen, wrong colors, misaligned text - upload a screenshot (drag and drop into the chat) and describe what you expected to see:\n\n```\nThis modal is cut off on mobile (see screenshot). The submit button is below the fold.\n```\n</Step>\n\n<Step title=\"Describe when it happens\">\nFor bugs that come and go, share the context:\n\n- **When** - \"only after I log in\" or \"on the second page load\"\n- **Where** - which page or feature\n- **What action** - the button click or form that triggers it\n\nThis helps the agent trace state or routing issues.\n</Step>\n</Steps>\n\n<Tip>\nRight-click an error in your browser console and select \"Copy\" to capture the full output, including all stack frames. To open browser console, right click anywhere on the page and click Inspect.\n</Tip>\n\n## If the agent is stuck in a loop\n\nThe platform has built-in loop detection, and detected loops may earn you an **automatic credit rebate** (it appears in your credit history). If the agent keeps circling anyway:\n\n1. **Stop repeating the same request.** Describe what went wrong and what to try instead.\n2. **Fork the conversation** (Fork button in the chat input bar, web app). A fork starts a fresh conversation from the current code state, the agent loses the bad pattern but keeps your app.\n3. If the agent seems unresponsive because the AI provider itself is degraded, fork and **switch to a different model** in the model selector, each model runs on separate provider infrastructure.\n\n## If the agent stopped: what stop reasons mean\n\n- **Finished normally**: the agent thinks it's done. If something's missing, just say what.\n- **Waiting for you**: it asked a question and paused. Answer to resume.\n- **Out of credits**: the job pauses; it resumes automatically after you top up.\n- **Context window full**: the conversation got too long. Agent will start auto-compacting the conversation till that point.\n- **Credit limit reached**: the maximum-credits-per-prompt cap you set in Settings → Billing was hit (this is separate from your account balance). Raise the budget or start a new job.\n- **Execution timeout**: the job hit the 4-hour limit. Break the task into smaller jobs.\n\n\n## Roll back when you can't describe the fix\n\n**Ask the agent** when the issue is small and you can describe what went wrong. **Roll back** when you're not sure what broke, or when multiple changes need undoing at once, the full how-to (and what rollback does and doesn't restore) is in [Checkpoints: undo anything](/checkpoints-undo-anything). Remember: rollback affects your **preview** only; **Re-publish** to update the live app.\n\n## Still stuck? What to send support\n\nIf a couple of rounds haven't fixed it, contact support with a package that lets them help on the first reply:\n\n1. **Your job ID**: open your job and click the **info (i) button** in the top panel. Copy the job ID from there. It's a long alpha-numeric string with a copy button at its side.\n2. **What you did, what you expected, what actually happened**: three short lines.\n3. **The full error text and/or a screenshot**: the same material from the steps above.\n4. **Where it happens**: preview, the live app, or both (this one detail localizes most problems).\n\nReach the team at [support@emergent.sh](mailto:support@emergent.sh).\n\n**Go deeper:** [Publishing issues](/deployment-issues) · [Getting help, support & community](/getting-help-support-community)\n","order":119,"parent_id":null,"icon":"wrench","description":"What to do when your app errors or looks wrong - fix it with one message.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-25T09:18:52.715539+00:00","published_at":"2026-09-25T09:18:52.715539+00:00","published_content":"\nA calm path for when your app has errors or doesn't look right: how to report a bug so it gets fixed in one round, how to tell *what kind* of problem you're looking at, and what to send support if you're stuck.\n\n## First: which of these is it?\n\nMost \"something broke\" moments are one of four situations, each with a different fix:\n\n| What you're seeing | What it usually is | What to do |\n|---|---|---|\n| Works in preview, broken on the live app | A **configuration difference** between the two environments, not the code | Check **Preview → Manage → Secrets**, production values are separate from preview. See [Works in preview but breaks in production](/works-in-preview-but-breaks-in-production) |\n| The agent repeats the same failing fix over and over | A **loop** (\"doom loop\") | Don't keep re-asking the same way. Pause it, describe what went wrong and what to do *differently*, or **fork** to give it a fresh start (see below) |\n| The agent stopped mid-job | A **stop reason**, often normal | See the stop-reasons list below |\n| A feature that worked yesterday is broken after new changes | A **regression** | **Roll back** to the last good point in the chat timeline (see [Checkpoints: undo anything](/checkpoints-undo-anything)), then re-request the new change more narrowly |\n\n<Callout type=\"note\" title=\"What 'verified' means\">\nWhen the agent says it **verified** a fix, that means it confirmed the fix works **in preview**, the agent has no access to your live app. If it works in preview, it should work live too *unless the two environments are configured differently*, which is why the first row above is so common.\n</Callout>\n\n## If you see an error message\n\n<Steps>\n<Step title=\"Copy the entire error\">\nWhen something breaks, grab the **full error text** from your browser console or the error modal - including stack traces, file paths, and line numbers. Paste it straight into the chat with a short note:\n\n```\nplease solve this error\n\n[paste the complete error here]\n```\n\nThe agent will read the stack trace, find the broken component or connection, and push a fix.\n</Step>\n\n<Step title=\"Add a screenshot for visual bugs\">\nIf the problem is visual - a button hidden off-screen, wrong colors, misaligned text - upload a screenshot (drag and drop into the chat) and describe what you expected to see:\n\n```\nThis modal is cut off on mobile (see screenshot). The submit button is below the fold.\n```\n</Step>\n\n<Step title=\"Describe when it happens\">\nFor bugs that come and go, share the context:\n\n- **When** - \"only after I log in\" or \"on the second page load\"\n- **Where** - which page or feature\n- **What action** - the button click or form that triggers it\n\nThis helps the agent trace state or routing issues.\n</Step>\n</Steps>\n\n<Tip>\nRight-click an error in your browser console and select \"Copy\" to capture the full output, including all stack frames. To open browser console, right click anywhere on the page and click Inspect.\n</Tip>\n\n## If the agent is stuck in a loop\n\nThe platform has built-in loop detection, and detected loops may earn you an **automatic credit rebate** (it appears in your credit history). If the agent keeps circling anyway:\n\n1. **Stop repeating the same request.** Describe what went wrong and what to try instead.\n2. **Fork the conversation** (Fork button in the chat input bar, web app). A fork starts a fresh conversation from the current code state, the agent loses the bad pattern but keeps your app.\n3. If the agent seems unresponsive because the AI provider itself is degraded, fork and **switch to a different model** in the model selector, each model runs on separate provider infrastructure.\n\n## If the agent stopped: what stop reasons mean\n\n- **Finished normally**: the agent thinks it's done. If something's missing, just say what.\n- **Waiting for you**: it asked a question and paused. Answer to resume.\n- **Out of credits**: the job pauses; it resumes automatically after you top up.\n- **Context window full**: the conversation got too long. Agent will start auto-compacting the conversation till that point.\n- **Credit limit reached**: the maximum-credits-per-prompt cap you set in Settings → Billing was hit (this is separate from your account balance). Raise the budget or start a new job.\n- **Execution timeout**: the job hit the 4-hour limit. Break the task into smaller jobs.\n\n\n## Roll back when you can't describe the fix\n\n**Ask the agent** when the issue is small and you can describe what went wrong. **Roll back** when you're not sure what broke, or when multiple changes need undoing at once, the full how-to (and what rollback does and doesn't restore) is in [Checkpoints: undo anything](/checkpoints-undo-anything). Remember: rollback affects your **preview** only; **Re-publish** to update the live app.\n\n## Still stuck? What to send support\n\nIf a couple of rounds haven't fixed it, contact support with a package that lets them help on the first reply:\n\n1. **Your job ID**: open your job and click the **info (i) button** in the top panel. Copy the job ID from there. It's a long alpha-numeric string with a copy button at its side.\n2. **What you did, what you expected, what actually happened**: three short lines.\n3. **The full error text and/or a screenshot**: the same material from the steps above.\n4. **Where it happens**: preview, the live app, or both (this one detail localizes most problems).\n\nReach the team at [support@emergent.sh](mailto:support@emergent.sh).\n\n**Go deeper:** [Publishing issues](/deployment-issues) · [Getting help, support & community](/getting-help-support-community)\n","published_title":"When something breaks","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"30752c60-0130-4b36-99e1-ad5f53fb1c3b","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Add login & user accounts","slug":"add-login-user-accounts","content":"\nYour app will have sign-up and login pages so each person gets their own private space and data.\n\n## Why you need accounts\n\nRight now, everyone who visits your app sees the same thing. If you're building a to-do list, a journal, or anything where people should have their own private information, you need user accounts. Once someone logs in, the app knows who they are and can show them only their own tasks, posts, or whatever you're building.\n\n## Meet Emergent Auth\n\n**Emergent Auth** is the platform's built-in authentication. It supports:\n\n- **Email and password**: the traditional way. Users pick a password and the app stores it securely (hashed, never in plain text). Works out of the box with zero setup.\n- **Google sign-in**: no keys needed, no Google Cloud Console setup. (Optionally, supply your own `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` env vars if you need custom consent-screen branding or extra scopes like Gmail or Calendar access.)\n\nIt works in both preview and production, sessions carry across publishing, and there are no API keys to configure.\n\n<Callout type=\"note\" title=\"Added on request\">\nEvery Emergent app includes authentication capabilities built in - you just ask the agent to wire up login and it does the rest. You just describe what you want in chat and the AI wires it up, with no extra billing required.\n</Callout>\n\n\n## Add login with a prompt\n\nTell the AI what you want in plain English:\n\n<Steps>\n<Step title=\"Describe sign-up and login\">\nType something like: *\"Users should be able to sign up with email and password, then log in to see their dashboard.\"*\n\nThe AI will create login and sign-up pages, handle sessions, and make sure people stay logged in when they come back.\n</Step>\n\n<Step title=\"Protect your pages\">\nIf you only want logged-in people to see certain pages, say: *\"Make the dashboard page require login.\"*\n\nVisitors who aren't signed in will be sent to the login page first.\n</Step>\n\n</Steps>\n\n\n## When to use something else\n\nEmergent Auth is optional. If you need **full control over the login experience**, a completely custom UI, or auth that lives with a provider you already use, you can integrate **Auth0**, **Clerk**, **Firebase Auth**, or **Supabase Auth** instead, and your users go through your chosen provider's flow. See [Connect your tools](/connect-your-tools).\n\n## See your users\n\nOnce people start signing up, their accounts are stored in your app's database.\n\n\nAccounts live in a collection, for e.g., it might be called 'User'. You can ask the AI to show you a list: *\"Show me all registered users in an admin page.\"* Each user record includes their email, when they signed up, and any extra fields you've added (like display name or profile picture).\n\n\n## If something looks wrong\n\n**People can't log in after signing up** - make sure you tested the sign-up flow yourself in preview and production modes.\n\n**You want to add profile pictures or other fields** - just describe it: *\"Add a displayName field to users so they can choose a nickname.\"* The AI will extend the user records and update the sign-up form. Make sure to do this before you publish for the first time because your database schema is set the first time you publish.\n\n**Sessions expire too fast** - Emergent Auth keeps people signed in using secure, server-side sessions. If the timeout doesn't suit your app, just describe what you want in chat: *\"Keep users logged in longer between visits.\"*\n\n\n**Go deeper:** [Emergent Auth](/emergent-auth-built-in)","order":120,"parent_id":null,"icon":"log-in","description":"Let people sign up and have their own data.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-25T10:37:37.039814+00:00","published_at":"2026-09-25T10:37:37.039814+00:00","published_content":"\nYour app will have sign-up and login pages so each person gets their own private space and data.\n\n## Why you need accounts\n\nRight now, everyone who visits your app sees the same thing. If you're building a to-do list, a journal, or anything where people should have their own private information, you need user accounts. Once someone logs in, the app knows who they are and can show them only their own tasks, posts, or whatever you're building.\n\n## Meet Emergent Auth\n\n**Emergent Auth** is the platform's built-in authentication. It supports:\n\n- **Email and password**: the traditional way. Users pick a password and the app stores it securely (hashed, never in plain text). Works out of the box with zero setup.\n- **Google sign-in**: no keys needed, no Google Cloud Console setup. (Optionally, supply your own `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` env vars if you need custom consent-screen branding or extra scopes like Gmail or Calendar access.)\n\nIt works in both preview and production, sessions carry across publishing, and there are no API keys to configure.\n\n<Callout type=\"note\" title=\"Added on request\">\nEvery Emergent app includes authentication capabilities built in - you just ask the agent to wire up login and it does the rest. You just describe what you want in chat and the AI wires it up, with no extra billing required.\n</Callout>\n\n\n## Add login with a prompt\n\nTell the AI what you want in plain English:\n\n<Steps>\n<Step title=\"Describe sign-up and login\">\nType something like: *\"Users should be able to sign up with email and password, then log in to see their dashboard.\"*\n\nThe AI will create login and sign-up pages, handle sessions, and make sure people stay logged in when they come back.\n</Step>\n\n<Step title=\"Protect your pages\">\nIf you only want logged-in people to see certain pages, say: *\"Make the dashboard page require login.\"*\n\nVisitors who aren't signed in will be sent to the login page first.\n</Step>\n\n</Steps>\n\n\n## When to use something else\n\nEmergent Auth is optional. If you need **full control over the login experience**, a completely custom UI, or auth that lives with a provider you already use, you can integrate **Auth0**, **Clerk**, **Firebase Auth**, or **Supabase Auth** instead, and your users go through your chosen provider's flow. See [Connect your tools](/connect-your-tools).\n\n## See your users\n\nOnce people start signing up, their accounts are stored in your app's database.\n\n\nAccounts live in a collection, for e.g., it might be called 'User'. You can ask the AI to show you a list: *\"Show me all registered users in an admin page.\"* Each user record includes their email, when they signed up, and any extra fields you've added (like display name or profile picture).\n\n\n## If something looks wrong\n\n**People can't log in after signing up** - make sure you tested the sign-up flow yourself in preview and production modes.\n\n**You want to add profile pictures or other fields** - just describe it: *\"Add a displayName field to users so they can choose a nickname.\"* The AI will extend the user records and update the sign-up form. Make sure to do this before you publish for the first time because your database schema is set the first time you publish.\n\n**Sessions expire too fast** - Emergent Auth keeps people signed in using secure, server-side sessions. If the timeout doesn't suit your app, just describe what you want in chat: *\"Keep users logged in longer between visits.\"*\n\n\n**Go deeper:** [Emergent Auth](/emergent-auth-built-in)","published_title":"Add login & user accounts","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"c0f11843-e949-4775-b1b5-d2a63bb89610","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Checkpoints: undo anything","slug":"checkpoints-undo-anything","content":"\n\n\n\nEvery agent turn is saved automatically as a checkpoint. You can roll your preview back to an earlier point, or fork the whole app to experiment safely, and you'll know exactly what each one does and doesn't restore.\n\n## How automatic checkpoints work\n\nEmergent saves a checkpoint **every time the agent finishes a turn**. Think of these as save points - if a change breaks something, you can return to the last point where everything worked.\n\n<Callout type=\"warning\" title=\"Know what rollback does before you use it\">\nRolling back **erases** the chat messages and code changes made *after* the point you choose (there's an option to erase messages only). There is **no roll-forward**: once you roll back and continue, the erased work is gone. When in doubt, **fork first** (below), the fork keeps a full copy while you experiment.\n</Callout>\n\n## Going back to an earlier version\n\nIf the agent breaks something - maybe it removed a button, deleted files you need, or misunderstood an instruction - roll back to a point when everything worked.\n\n<Steps>\n<Step title=\"Find the message to return to\">\nRollback lives on the **chat timeline**: each message has a **Rollback button**. Scroll to the last message where the app was in a good state.\n</Step>\n\n<Step title=\"Choose what to erase\">\nYou can erase **messages and code** (the full revert) or **messages only**.\n</Step>\n\n<Step title=\"Confirm the rollback\">\nClick **Rollback**. Your **preview** is restored to that point. Rollback affects preview only, your live app keeps running its last published version until you **Re-publish**. Your app's web address and database records are unchanged.\n</Step>\n</Steps>\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/d54f26a64f35469cbb905f366616883d.mov\" />\n\n## Experimenting without risk: forking\n\nSometimes you don't want to undo - you want to **try something big** without touching your working app. That's what **forking** is for.\n\nForking creates a complete, independent copy of your app. The original keeps running; the copy (the \"fork\") becomes a separate job where you can experiment freely.\n\n<Steps>\n<Step title=\"Click Fork\">\nClick the **+ button** in the chat input bar, then click **Fork this chat**.\n</Step>\n\n<Step title=\"Configure the new chat\">\nThe **Configure New Chat** dialog opens: your chat history is condensed into an editable **summary** the fork starts from (review it, add anything important), and you can pick the model for the new chat.\n</Step>\n\n\n<Step title=\"Build independently\">\nThe fork appears as its own job. Chat, build, and publish in the fork without affecting the original. If the experiment works, keep the fork. If it fails, just delete it and go back to the original.\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Fork before risky changes\">\nThinking of asking the agent to \"refactor the entire backend\"? Fork first. If things go sideways, you haven't lost anything, the fork is a full copy of your code **and data**.\n</Callout>\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/c569c238b25a4d388be55951bda6058b.png\" alt=\"Fork button\" caption=\"Fork button\" />\n\n### What gets copied when you fork\n\n- **All your code and files** at the moment of the fork\n- **Database contents** (code and data are cloned from the volume at the fork point)\n- **Chat history** up to the fork point is **summarized** (editable) in the new job, it is not carried verbatim, so early details may need re-stating\n- **Build settings**, and the files in your project (including `.env`) come along with the codebase - but secrets you set in the platform's Secrets panel are **not** copied. Re-add those in the fork before publishing.\n\n\n## Rollback vs. fork: when to use each\n\n| You want to... | Use |\n|----------------|-----|\n| Undo a recent bad change | **Rollback** |\n| Try a big experiment without touching the working app | **Fork** |\n| Build a variant for a different customer or use case | **Fork** |\n| Escape an agent that's stuck repeating itself | **Fork** (fresh conversation from the current code state, see [When something breaks](/when-something-breaks)) |\n| Recover from multiple mistakes over time | Rollback to a known-good state, *then* fork if you want to explore a different direction in parallel |\n\n<Callout type=\"info\" title=\"Think of it this way\">\nRollback is \"undo back to a point\" (and it erases what came after). Forking is \"duplicate and diverge\" (nothing is erased).\n</Callout>\n\n## If something looks wrong after rolling back\n\nRollback restores your **preview** code to the selected point in the chat timeline. **Re-publish** to update the live app. If the old code expects the database to look different than it does now, you might see errors until you manually clean up or adjust the data.\n\n\n<Callout type=\"note\" title=\"What rollback includes\">\n✅ All source code files  \n✅ Dependencies and packages  \n✅ Environment variables  \n✅ Build configuration  \n✅ Database structure (table structures, indexes)\n\n❌ Database data (your actual records stay as-is)  \n❌ External connection keys stored outside the platform  \n❌ Custom domain DNS records\n</Callout>\n\nAlways test your app after a rollback to make sure critical features still work.\n\n\n**Go deeper:** [Forking](/forking)","order":121,"parent_id":null,"icon":"history","description":"Every change is saved automatically. Go back anytime - nothing is ever lost.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:17:01.024004+00:00","published_at":"2026-09-24T14:17:01.024004+00:00","published_content":"\n\n\n\nEvery agent turn is saved automatically as a checkpoint. You can roll your preview back to an earlier point, or fork the whole app to experiment safely, and you'll know exactly what each one does and doesn't restore.\n\n## How automatic checkpoints work\n\nEmergent saves a checkpoint **every time the agent finishes a turn**. Think of these as save points - if a change breaks something, you can return to the last point where everything worked.\n\n<Callout type=\"warning\" title=\"Know what rollback does before you use it\">\nRolling back **erases** the chat messages and code changes made *after* the point you choose (there's an option to erase messages only). There is **no roll-forward**: once you roll back and continue, the erased work is gone. When in doubt, **fork first** (below), the fork keeps a full copy while you experiment.\n</Callout>\n\n## Going back to an earlier version\n\nIf the agent breaks something - maybe it removed a button, deleted files you need, or misunderstood an instruction - roll back to a point when everything worked.\n\n<Steps>\n<Step title=\"Find the message to return to\">\nRollback lives on the **chat timeline**: each message has a **Rollback button**. Scroll to the last message where the app was in a good state.\n</Step>\n\n<Step title=\"Choose what to erase\">\nYou can erase **messages and code** (the full revert) or **messages only**.\n</Step>\n\n<Step title=\"Confirm the rollback\">\nClick **Rollback**. Your **preview** is restored to that point. Rollback affects preview only, your live app keeps running its last published version until you **Re-publish**. Your app's web address and database records are unchanged.\n</Step>\n</Steps>\n\n<Video src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/videos/d54f26a64f35469cbb905f366616883d.mov\" />\n\n## Experimenting without risk: forking\n\nSometimes you don't want to undo - you want to **try something big** without touching your working app. That's what **forking** is for.\n\nForking creates a complete, independent copy of your app. The original keeps running; the copy (the \"fork\") becomes a separate job where you can experiment freely.\n\n<Steps>\n<Step title=\"Click Fork\">\nClick the **+ button** in the chat input bar, then click **Fork this chat**.\n</Step>\n\n<Step title=\"Configure the new chat\">\nThe **Configure New Chat** dialog opens: your chat history is condensed into an editable **summary** the fork starts from (review it, add anything important), and you can pick the model for the new chat.\n</Step>\n\n\n<Step title=\"Build independently\">\nThe fork appears as its own job. Chat, build, and publish in the fork without affecting the original. If the experiment works, keep the fork. If it fails, just delete it and go back to the original.\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Fork before risky changes\">\nThinking of asking the agent to \"refactor the entire backend\"? Fork first. If things go sideways, you haven't lost anything, the fork is a full copy of your code **and data**.\n</Callout>\n<Figure src=\"/api/public/files/emergent-docs/d901b4ab-a271-4aff-b63a-bf92d73b9bb0/images/c569c238b25a4d388be55951bda6058b.png\" alt=\"Fork button\" caption=\"Fork button\" />\n\n### What gets copied when you fork\n\n- **All your code and files** at the moment of the fork\n- **Database contents** (code and data are cloned from the volume at the fork point)\n- **Chat history** up to the fork point is **summarized** (editable) in the new job, it is not carried verbatim, so early details may need re-stating\n- **Build settings**, and the files in your project (including `.env`) come along with the codebase - but secrets you set in the platform's Secrets panel are **not** copied. Re-add those in the fork before publishing.\n\n\n## Rollback vs. fork: when to use each\n\n| You want to... | Use |\n|----------------|-----|\n| Undo a recent bad change | **Rollback** |\n| Try a big experiment without touching the working app | **Fork** |\n| Build a variant for a different customer or use case | **Fork** |\n| Escape an agent that's stuck repeating itself | **Fork** (fresh conversation from the current code state, see [When something breaks](/when-something-breaks)) |\n| Recover from multiple mistakes over time | Rollback to a known-good state, *then* fork if you want to explore a different direction in parallel |\n\n<Callout type=\"info\" title=\"Think of it this way\">\nRollback is \"undo back to a point\" (and it erases what came after). Forking is \"duplicate and diverge\" (nothing is erased).\n</Callout>\n\n## If something looks wrong after rolling back\n\nRollback restores your **preview** code to the selected point in the chat timeline. **Re-publish** to update the live app. If the old code expects the database to look different than it does now, you might see errors until you manually clean up or adjust the data.\n\n\n<Callout type=\"note\" title=\"What rollback includes\">\n✅ All source code files  \n✅ Dependencies and packages  \n✅ Environment variables  \n✅ Build configuration  \n✅ Database structure (table structures, indexes)\n\n❌ Database data (your actual records stay as-is)  \n❌ External connection keys stored outside the platform  \n❌ Custom domain DNS records\n</Callout>\n\nAlways test your app after a rollback to make sure critical features still work.\n\n\n**Go deeper:** [Forking](/forking)","published_title":"Checkpoints: undo anything","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"db16ba78-2dba-44e5-9a1b-9bcea7f2fd7f","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"How credits work","slug":"how-credits-work-basics","content":"\nA quick overview of what credits are, which parts of building an app use them, and how to add more when you need to.\n\n**Costs at a glance:** Emergent uses credits to measure the work the platform does for you - writing code, running tests, making your app live. You only pay for what you use. Credits can be added one-time (they never expire) or as part of a monthly plan (subscription credits refill to the plan cap each billing cycle and do not roll over).\n\n---\n\n## What credits are\n\nCredits are how Emergent measures usage. Every time the platform does work for you - writing code from a prompt, running tests, making your app live - it uses a few credits from your account. You'll see your current balance in the top-right corner of the workspace.\n\nThis means you only pay for what you actually use.\n\n---\n\n## What uses credits\n\nCredits get deducted when the platform performs any of these tasks:\n\n- **Code generation** - Each prompt that writes, changes or extends your app's code uses credits. Bigger changes and more complex files cost more.\n\n- **Testing** - Automated tests (unit tests, integration checks, visual scans) all use credits. More thorough test suites use more per run.\n\n- **Making your app live** - Publishing your app uses a fixed monthly tier fee (Starter, Launch, Grow, Scale, or Elite), not a variable charge based on build time or app size.\n\n- **Connections to other services & background tasks** - Calling a connection to another service (API), running scheduled jobs and background workers each deduct credits.\n\n- **Where your app stores its information (database) operations** - Heavy database work (large queries, bulk inserts) incurs small incremental charges.\n\n- **LLM calls from your app** - If your *app itself* calls language models at runtime using [the Universal LLM Key](/the-universal-llm-key), those API calls are billed through your Emergent credits.\n\n<Callout type=\"note\" title=\"Maxx mode uses more\">\nWhen you turn on **Maxx mode** (the toggle in the prompt bar), the platform plans more carefully and runs deeper checks. You'll get higher-quality results, but it uses significantly more credits than a normal prompt.\n</Callout>\n\n---\n\n## How much a prompt costs\n\nA single prompt can use anywhere from a handful of credits (for a small change to how your app looks and feels) to hundreds (for a full feature with tests and making it live).\n\n\n<Callout type=\"tip\" title=\"Set a spending limit\">\nWhen starting a task, you can set a **per-session budget** on the task form. If the agent exhausts that budget during a run, it pauses automatically, so you stay in control of spending. See [Managing credit usage](/managing-credit-usage) to track and manage limits.\n</Callout>\n\n---\n\n## Checking your balance & topping up\n\nYou can view your credit balance and usage breakdown in **Account Settings → Credit Usage**, where you'll see consumption by category (agent runs, published versions, Universal Key calls, and more).\n\nYou'll get an email alert when your balance drops below 20 % of your monthly allowance.\n\n**To add more credits:**\n- **One-time top-ups** never expire and roll over indefinitely.\n- **Monthly plan credits** refill to the plan cap at each billing cycle and do not roll over.\n- Emergent always spends expiring credits first, so you get the most value.\n\n<Callout type=\"warning\" title=\"If you hit zero\">\nIf your balance reaches zero during a build or making your app live, the operation will pause. You can resume immediately by adding credits - no work is lost, but your app won't go live until the process finishes.\n</Callout>\n\n---\n\n## Want more detail?\n\nFor a complete breakdown of credit rates, volume discounts and billing mechanics, see the full [Managing credit usage](/managing-credit-usage) reference.\n\n**Go deeper:** [Managing credit usage](/managing-credit-usage) · [Plans & the free tier](/plans-the-free-tier)","order":122,"parent_id":null,"icon":"coins","description":"What uses credits, what doesn't, and what a first app typically costs.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.254064+00:00","published_at":"2026-09-24T14:08:37.254064+00:00","published_content":"\nA quick overview of what credits are, which parts of building an app use them, and how to add more when you need to.\n\n**Costs at a glance:** Emergent uses credits to measure the work the platform does for you - writing code, running tests, making your app live. You only pay for what you use. Credits can be added one-time (they never expire) or as part of a monthly plan (subscription credits refill to the plan cap each billing cycle and do not roll over).\n\n---\n\n## What credits are\n\nCredits are how Emergent measures usage. Every time the platform does work for you - writing code from a prompt, running tests, making your app live - it uses a few credits from your account. You'll see your current balance in the top-right corner of the workspace.\n\nThis means you only pay for what you actually use.\n\n---\n\n## What uses credits\n\nCredits get deducted when the platform performs any of these tasks:\n\n- **Code generation** - Each prompt that writes, changes or extends your app's code uses credits. Bigger changes and more complex files cost more.\n\n- **Testing** - Automated tests (unit tests, integration checks, visual scans) all use credits. More thorough test suites use more per run.\n\n- **Making your app live** - Publishing your app uses a fixed monthly tier fee (Starter, Launch, Grow, Scale, or Elite), not a variable charge based on build time or app size.\n\n- **Connections to other services & background tasks** - Calling a connection to another service (API), running scheduled jobs and background workers each deduct credits.\n\n- **Where your app stores its information (database) operations** - Heavy database work (large queries, bulk inserts) incurs small incremental charges.\n\n- **LLM calls from your app** - If your *app itself* calls language models at runtime using [the Universal LLM Key](/the-universal-llm-key), those API calls are billed through your Emergent credits.\n\n<Callout type=\"note\" title=\"Maxx mode uses more\">\nWhen you turn on **Maxx mode** (the toggle in the prompt bar), the platform plans more carefully and runs deeper checks. You'll get higher-quality results, but it uses significantly more credits than a normal prompt.\n</Callout>\n\n---\n\n## How much a prompt costs\n\nA single prompt can use anywhere from a handful of credits (for a small change to how your app looks and feels) to hundreds (for a full feature with tests and making it live).\n\n\n<Callout type=\"tip\" title=\"Set a spending limit\">\nWhen starting a task, you can set a **per-session budget** on the task form. If the agent exhausts that budget during a run, it pauses automatically, so you stay in control of spending. See [Managing credit usage](/managing-credit-usage) to track and manage limits.\n</Callout>\n\n---\n\n## Checking your balance & topping up\n\nYou can view your credit balance and usage breakdown in **Account Settings → Credit Usage**, where you'll see consumption by category (agent runs, published versions, Universal Key calls, and more).\n\nYou'll get an email alert when your balance drops below 20 % of your monthly allowance.\n\n**To add more credits:**\n- **One-time top-ups** never expire and roll over indefinitely.\n- **Monthly plan credits** refill to the plan cap at each billing cycle and do not roll over.\n- Emergent always spends expiring credits first, so you get the most value.\n\n<Callout type=\"warning\" title=\"If you hit zero\">\nIf your balance reaches zero during a build or making your app live, the operation will pause. You can resume immediately by adding credits - no work is lost, but your app won't go live until the process finishes.\n</Callout>\n\n---\n\n## Want more detail?\n\nFor a complete breakdown of credit rates, volume discounts and billing mechanics, see the full [Managing credit usage](/managing-credit-usage) reference.\n\n**Go deeper:** [Managing credit usage](/managing-credit-usage) · [Plans & the free tier](/plans-the-free-tier)","published_title":"How credits work","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"b8793ac4-47bf-4038-8da3-6efae3090920","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Get your first users","slug":"get-your-first-users","content":"\nA simple launch checklist, the best places to share your app, and a practical way to turn early feedback into your next set of changes.\n\n---\n\nBefore the push: run the full pass in [Try it before you share it](/try-it-before-you-share-it), confirm your live URL in an incognito tab, and check that Manage Publishing shows Live, then start here.\n\n---\n\n## Where to share your app\n\nOnce your app is live you have a permanent public link - share it wherever your potential users already are:\n\n-   **People you know** - text it to friends, family and colleagues, and ask them to try one specific thing.\n-   **Group chats and communities** - WhatsApp/Slack/Discord groups, and subreddits or forums focused on your app's topic.\n-   **Social media** - post the link on X, LinkedIn, or Instagram with a one-line description of what it does and who it's for.\n-   **Niche communities** - places where your target users gather (a hobby forum, a professional group, a local community board).\n-   **Your profile** - add it to your bio, portfolio, or email signature so it keeps getting seen.\n\n<Callout type=\"tip\" title=\"Lead with the problem you solve\">\n\"I built a tool that turns your grocery receipts into a monthly spending chart\" gets more clicks than \"check out my new app\". Say what it does and who it's for in one line.\n</Callout>\n\n---\n\n## Asking for feedback\n\nEarly feedback is most useful when you make it easy to give:\n\n-   **Ask a specific question** instead of \"what do you think?\" - try \"was anything confusing on the sign-up screen?\" or \"did the main action work on your phone?\".\n-   **Give testers a task** - \"try adding an item and deleting it\" - and watch where they hesitate.\n-   **Watch someone use it live** if you can (in person or a screen-share). You'll learn more from thirty seconds of watching than a page of written notes.\n-   **Collect it somewhere simple** - a group chat, direct messages, or a short form. If you want responses captured inside the product, you can ask the agent to add a simple feedback form to your app.\n\n<Callout type=\"tip\" title=\"Keep the ask small\">\nPeople are far more likely to reply to one focused question than a long survey. Ask one thing, act on it, then ask the next.\n</Callout>\n\n---\n\n## Turning early feedback into next steps\n\nReal feedback often surprises you - things you thought were obvious confuse people, and small requests turn out to matter a lot. Here's how to act on it:\n\n<Steps>\n<Step title=\"Group feedback into themes\">\nCollect everything in one place and cluster it - \"sign-up is confusing\", \"wanted dark mode\", \"button too small on mobile\". Patterns matter more than one-off opinions.\n</Step>\n<Step title=\"Pick the highest-impact fix\">\nStart with whatever blocks people from getting value (a broken flow or a confusing first screen) before nice-to-haves.\n</Step>\n<Step title=\"Turn it into a clear prompt\">\nDescribe the change to the agent as one concrete request - \"On mobile, the Add button is hard to tap; make it a larger floating button.\" See [Write prompts that work](/write-prompts-that-work) for how to phrase these well.\n</Step>\n<Step title=\"Iterate in preview, then push it live\">\nMake and test the change in your preview, then re-publish so visitors see it. Preview and live are separate - the difference is explained in [Preview vs Published](/preview-vs-deployed-separate).\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Small loops beat big rewrites\">\nShip one improvement, tell the people who gave feedback, and ask again. A few fast rounds will teach you more than a single big update.\n</Callout>\n","order":123,"parent_id":null,"icon":"users","description":"A simple launch checklist to get your app in front of real people.","created_at":"2026-08-25T12:46:25.486544+00:00","updated_at":"2026-09-24T14:08:37.260253+00:00","published_at":"2026-09-24T14:08:37.260253+00:00","published_content":"\nA simple launch checklist, the best places to share your app, and a practical way to turn early feedback into your next set of changes.\n\n---\n\nBefore the push: run the full pass in [Try it before you share it](/try-it-before-you-share-it), confirm your live URL in an incognito tab, and check that Manage Publishing shows Live, then start here.\n\n---\n\n## Where to share your app\n\nOnce your app is live you have a permanent public link - share it wherever your potential users already are:\n\n-   **People you know** - text it to friends, family and colleagues, and ask them to try one specific thing.\n-   **Group chats and communities** - WhatsApp/Slack/Discord groups, and subreddits or forums focused on your app's topic.\n-   **Social media** - post the link on X, LinkedIn, or Instagram with a one-line description of what it does and who it's for.\n-   **Niche communities** - places where your target users gather (a hobby forum, a professional group, a local community board).\n-   **Your profile** - add it to your bio, portfolio, or email signature so it keeps getting seen.\n\n<Callout type=\"tip\" title=\"Lead with the problem you solve\">\n\"I built a tool that turns your grocery receipts into a monthly spending chart\" gets more clicks than \"check out my new app\". Say what it does and who it's for in one line.\n</Callout>\n\n---\n\n## Asking for feedback\n\nEarly feedback is most useful when you make it easy to give:\n\n-   **Ask a specific question** instead of \"what do you think?\" - try \"was anything confusing on the sign-up screen?\" or \"did the main action work on your phone?\".\n-   **Give testers a task** - \"try adding an item and deleting it\" - and watch where they hesitate.\n-   **Watch someone use it live** if you can (in person or a screen-share). You'll learn more from thirty seconds of watching than a page of written notes.\n-   **Collect it somewhere simple** - a group chat, direct messages, or a short form. If you want responses captured inside the product, you can ask the agent to add a simple feedback form to your app.\n\n<Callout type=\"tip\" title=\"Keep the ask small\">\nPeople are far more likely to reply to one focused question than a long survey. Ask one thing, act on it, then ask the next.\n</Callout>\n\n---\n\n## Turning early feedback into next steps\n\nReal feedback often surprises you - things you thought were obvious confuse people, and small requests turn out to matter a lot. Here's how to act on it:\n\n<Steps>\n<Step title=\"Group feedback into themes\">\nCollect everything in one place and cluster it - \"sign-up is confusing\", \"wanted dark mode\", \"button too small on mobile\". Patterns matter more than one-off opinions.\n</Step>\n<Step title=\"Pick the highest-impact fix\">\nStart with whatever blocks people from getting value (a broken flow or a confusing first screen) before nice-to-haves.\n</Step>\n<Step title=\"Turn it into a clear prompt\">\nDescribe the change to the agent as one concrete request - \"On mobile, the Add button is hard to tap; make it a larger floating button.\" See [Write prompts that work](/write-prompts-that-work) for how to phrase these well.\n</Step>\n<Step title=\"Iterate in preview, then push it live\">\nMake and test the change in your preview, then re-publish so visitors see it. Preview and live are separate - the difference is explained in [Preview vs Published](/preview-vs-deployed-separate).\n</Step>\n</Steps>\n\n<Callout type=\"tip\" title=\"Small loops beat big rewrites\">\nShip one improvement, tell the people who gave feedback, and ask again. A few fast rounds will teach you more than a single big update.\n</Callout>\n","published_title":"Get your first users","status":"published","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"d8ad85b8-03cd-43b8-9a25-5515a5cc9b79","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"privacy-gdpr-overview","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.828184+00:00","published_content":"## Privacy & GDPR at Emergent\n\nThis section explains, in plain language, how Emergent handles your data and where to find the authoritative detail. Wherever a specific rule matters, we point you to the exact document and section rather than paraphrasing it.\n\n<Callout type=\"info\" title=\"The short version\">\nYour customer data is processed and stored in **the United States, the EU and India** (DPA Annex 1). Access is limited and governed by our **Data Processing Agreement (DPA)**. We do **not** use your Customer Personal Data to train, retrain or fine-tune any AI or machine-learning model, and we contractually prohibit each AI sub-processor from doing so (DPA 12.1). Service Data, which the DPA defines separately from Customer Personal Data, may be used to train models that deliver the Services (DPA 11.1).\n</Callout>\n\n## The documents that govern your data\n\n<CardGroup cols={2}>\n<Card title=\"Data Processing Agreement (DPA)\" icon=\"file-text\" href=\"https://app.emergent.sh/dpa\">\nOur GDPR Article 28 agreement, with the EU Standard Contractual Clauses and UK Addendum built in.\n</Card>\n<Card title=\"Sub-processor list\" icon=\"users\" href=\"https://app.emergent.sh/subprocessors\">\nThe vendors in the data path, what we use them for, and where they process data.\n</Card>\n<Card title=\"Privacy Policy\" icon=\"shield\" href=\"https://app.emergent.sh/privacy-policy\">\nHow Emergent collects and uses personal data across the service.\n</Card>\n<Card title=\"Trust Centre\" icon=\"badge-check\" href=\"https://emergent.trust.site\">\nSecurity posture and current platform status.\n</Card>\n</CardGroup>\n\n## Where to send privacy questions\n\nSend privacy, GDPR or legal questions to **privacy@emergent.sh**. When you do, quote the relevant section and link the page you're asking about, that gets you an accurate answer fastest.\n\n<Note>\nFor anything a regulator or your own compliance team will file (for example a written confirmation of deletion, an audit request, or a security questionnaire), always route to **privacy@emergent.sh**. General product help stays at support@emergent.sh.\n</Note>\n\n## Analytics on your published app\n\nApps published on Emergent include platform analytics by default: first-party usage cookies and an analytics script that help measure traffic and reliability. If you do not want the analytics script in your app, ask the agent to remove it, then re-publish.\n","published_title":"Privacy & GDPR overview","title":"Privacy & GDPR overview","content":"## Privacy & GDPR at Emergent\n\nThis section explains, in plain language, how Emergent handles your data and where to find the authoritative detail. Wherever a specific rule matters, we point you to the exact document and section rather than paraphrasing it.\n\n<Callout type=\"info\" title=\"The short version\">\nYour customer data is processed and stored in **the United States, the EU and India** (DPA Annex 1). Access is limited and governed by our **Data Processing Agreement (DPA)**. We do **not** use your Customer Personal Data to train, retrain or fine-tune any AI or machine-learning model, and we contractually prohibit each AI sub-processor from doing so (DPA 12.1). Service Data, which the DPA defines separately from Customer Personal Data, may be used to train models that deliver the Services (DPA 11.1).\n</Callout>\n\n## The documents that govern your data\n\n<CardGroup cols={2}>\n<Card title=\"Data Processing Agreement (DPA)\" icon=\"file-text\" href=\"https://app.emergent.sh/dpa\">\nOur GDPR Article 28 agreement, with the EU Standard Contractual Clauses and UK Addendum built in.\n</Card>\n<Card title=\"Sub-processor list\" icon=\"users\" href=\"https://app.emergent.sh/subprocessors\">\nThe vendors in the data path, what we use them for, and where they process data.\n</Card>\n<Card title=\"Privacy Policy\" icon=\"shield\" href=\"https://app.emergent.sh/privacy-policy\">\nHow Emergent collects and uses personal data across the service.\n</Card>\n<Card title=\"Trust Centre\" icon=\"badge-check\" href=\"https://emergent.trust.site\">\nSecurity posture and current platform status.\n</Card>\n</CardGroup>\n\n## Where to send privacy questions\n\nSend privacy, GDPR or legal questions to **privacy@emergent.sh**. When you do, quote the relevant section and link the page you're asking about, that gets you an accurate answer fastest.\n\n<Note>\nFor anything a regulator or your own compliance team will file (for example a written confirmation of deletion, an audit request, or a security questionnaire), always route to **privacy@emergent.sh**. General product help stays at support@emergent.sh.\n</Note>\n\n## Analytics on your published app\n\nApps published on Emergent include platform analytics by default: first-party usage cookies and an analytics script that help measure traffic and reliability. If you do not want the analytics script in your app, ask the agent to remove it, then re-publish.\n","icon":"shield","description":"How Emergent handles your data and where to find the authoritative detail.","order":300,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.828184+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"c36b727d-3e3f-4265-a1e3-402ba989050c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"data-processing-agreement","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.830581+00:00","published_content":"## Our Data Processing Agreement\n\nEmergent's Data Processing Agreement is published at **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**. It is drafted to satisfy **Article 28 of the GDPR** and incorporates the **EU Standard Contractual Clauses** and the **UK Addendum** for international transfers.\n\n<Callout type=\"success\" title=\"It is self-executing, no signature needed\">\nThe DPA forms part of our Terms of Service and applies to every customer on every plan. By entering into the Agreement you have already accepted and executed it, including the Standard Contractual Clauses and their annexes. **Both parties are taken to have signed on the effective date of your Agreement** (see the Background section, paragraph D, and the signature block in Annex 1).\n</Callout>\n\n<Note>\nIf you need a countersigned PDF for your own records, that is a legal request, write to **privacy@emergent.sh**.\n</Note>\n\n## Standard Contractual Clauses & international transfers\n\nThe SCCs are incorporated into the DPA by reference (Section 9.2):\n\n- **Module Two** applies where you are a controller.\n- **Module Three** applies where you are yourself a processor.\n- For transfers out of the UK, the **UK Addendum** applies (Section 9.3).\n- Where the SCCs conflict with anything else in the DPA, the **SCCs prevail** (Section 9.6).\n\n## Contracting entity & data protection contact\n\n**Emergent Labs Inc.**, 255 California Street, Suite 550, San Francisco, CA 94111. . It acts as **processor** (or sub-processor, where you are yourself a processor for your own customers).\n\nOur data protection contact is **privacy@emergent.sh** (DPA Section 3.10 and Annex 1). Our Article 27 representative in the European Union is Prighter EU Rep GmbH, Schellinggasse 3/10, 1010 Vienna, Austria; in the United Kingdom it is Prighter Ltd, 20 Mortlake High Street, London SW14 8JN.\n\n<Tip>\nFull text is always the source of truth: **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**. Quote the section and link the page rather than interpreting a clause.\n</Tip>\n","published_title":"Data Processing Agreement (DPA)","title":"Data Processing Agreement (DPA)","content":"## Our Data Processing Agreement\n\nEmergent's Data Processing Agreement is published at **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**. It is drafted to satisfy **Article 28 of the GDPR** and incorporates the **EU Standard Contractual Clauses** and the **UK Addendum** for international transfers.\n\n<Callout type=\"success\" title=\"It is self-executing, no signature needed\">\nThe DPA forms part of our Terms of Service and applies to every customer on every plan. By entering into the Agreement you have already accepted and executed it, including the Standard Contractual Clauses and their annexes. **Both parties are taken to have signed on the effective date of your Agreement** (see the Background section, paragraph D, and the signature block in Annex 1).\n</Callout>\n\n<Note>\nIf you need a countersigned PDF for your own records, that is a legal request, write to **privacy@emergent.sh**.\n</Note>\n\n## Standard Contractual Clauses & international transfers\n\nThe SCCs are incorporated into the DPA by reference (Section 9.2):\n\n- **Module Two** applies where you are a controller.\n- **Module Three** applies where you are yourself a processor.\n- For transfers out of the UK, the **UK Addendum** applies (Section 9.3).\n- Where the SCCs conflict with anything else in the DPA, the **SCCs prevail** (Section 9.6).\n\n## Contracting entity & data protection contact\n\n**Emergent Labs Inc.**, 255 California Street, Suite 550, San Francisco, CA 94111. . It acts as **processor** (or sub-processor, where you are yourself a processor for your own customers).\n\nOur data protection contact is **privacy@emergent.sh** (DPA Section 3.10 and Annex 1). Our Article 27 representative in the European Union is Prighter EU Rep GmbH, Schellinggasse 3/10, 1010 Vienna, Austria; in the United Kingdom it is Prighter Ltd, 20 Mortlake High Street, London SW14 8JN.\n\n<Tip>\nFull text is always the source of truth: **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**. Quote the section and link the page rather than interpreting a clause.\n</Tip>\n","icon":"file-text","description":"Our GDPR Article 28 agreement, SCCs and UK Addendum, and why it's self-executing.","order":301,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.830581+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"7d4ab6fc-45eb-428d-b0d6-2671f75b7b0c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"where-your-data-is-stored","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.830804+00:00","published_content":"## Where your data lives\n\nYour customer data is **processed and stored in the United States, the EU and India** (DPA Annex 1).\n\nThe processing location for each individual sub-processor is listed at **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**.\n\n<Callout type=\"info\" title=\"Region selection\">\nYou can choose your published app's hosting region yourself: click **Re-publish** to open the **Manage Publishing** panel, go to the **Resources** tab, and change the region there. The EU region is priced higher than the US region, so changing region changes your publishing cost.\n</Callout>\n\n<Note>\nThe hosting region applies to your published app. The processing locations of individual sub-processors are unchanged by it - see the list above. If you have a broader compliance requirement about where your data lives, contact **privacy@emergent.sh**.\n</Note>\n\n## Who processes your data\n\nOur sub-processor list is published at **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. It names each sub-processor, what we use it for, and where it processes data.\n\n<Callout type=\"info\" title=\"You are kept informed of changes\">\nWe inform customers of intended additions or replacements by updating the published sub-processor list (DPA Section 8.2). The list is reviewed **at least annually**. You have **20 business days** from notification to object to a new sub-processor on reasonable data-protection grounds, by writing to **privacy@emergent.sh** (DPA Section 8.3). This applies on every plan.\n</Callout>\n\n## Emergent stays responsible\n\nWe remain **fully liable** to you for each sub-processor's performance, in line with **Article 28(4) GDPR** (DPA Section 8.6). Each sub-processor is bound by data-protection terms at least as protective as those in our DPA.\n\n<Note>\nFor the current vendor list, purposes and processing locations, always check the live page: **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. If you have a question about a specific vendor, write to **privacy@emergent.sh** and link the entry.\n</Note>\n","published_title":"Where your data is stored & who processes it","title":"Where your data is stored & who processes it","content":"## Where your data lives\n\nYour customer data is **processed and stored in the United States, the EU and India** (DPA Annex 1).\n\nThe processing location for each individual sub-processor is listed at **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**.\n\n<Callout type=\"info\" title=\"Region selection\">\nYou can choose your published app's hosting region yourself: click **Re-publish** to open the **Manage Publishing** panel, go to the **Resources** tab, and change the region there. The EU region is priced higher than the US region, so changing region changes your publishing cost.\n</Callout>\n\n<Note>\nThe hosting region applies to your published app. The processing locations of individual sub-processors are unchanged by it - see the list above. If you have a broader compliance requirement about where your data lives, contact **privacy@emergent.sh**.\n</Note>\n\n## Who processes your data\n\nOur sub-processor list is published at **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. It names each sub-processor, what we use it for, and where it processes data.\n\n<Callout type=\"info\" title=\"You are kept informed of changes\">\nWe inform customers of intended additions or replacements by updating the published sub-processor list (DPA Section 8.2). The list is reviewed **at least annually**. You have **20 business days** from notification to object to a new sub-processor on reasonable data-protection grounds, by writing to **privacy@emergent.sh** (DPA Section 8.3). This applies on every plan.\n</Callout>\n\n## Emergent stays responsible\n\nWe remain **fully liable** to you for each sub-processor's performance, in line with **Article 28(4) GDPR** (DPA Section 8.6). Each sub-processor is bound by data-protection terms at least as protective as those in our DPA.\n\n<Note>\nFor the current vendor list, purposes and processing locations, always check the live page: **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. If you have a question about a specific vendor, write to **privacy@emergent.sh** and link the entry.\n</Note>\n","icon":"map-pin","description":"Your customer data is processed and stored in the US and India.","order":303,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.830804+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"85521b94-de64-4a90-8fba-d78d613cdce7","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"ai-model-training","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.833797+00:00","published_content":"## We do not train AI on your personal data\n\n<Callout type=\"success\" title=\"Your data is not training data\">\nEmergent does **not** use your Customer Personal Data to train, retrain, fine-tune or otherwise develop any AI or machine-learning model, and we **contractually prohibit** each sub-processor that provides AI models from doing so (DPA Section 12.1).\n</Callout>\n\nYour Customer Personal Data is processed **solely to provide, maintain, secure and support the Services** (DPA Section 12.2).\n\n## What the AI providers see\n\nEmergent uses third-party language models to power the agents. The providers in use, and the countries in which they process data, are listed at  **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. They receive the prompt data needed to build your app: your prompts and instructions, conversation history, any files you upload, the code and files generated for you, and your database schema where it is part of the build context. Where you use those features, they also receive voice audio submitted for transcription and content entered by an agent operating a hosted browser. All of it is processed under the same DPA protections, and they are prohibited from training on it.\n\n<Note>\nService Data - operational data about how the Services are used, which the DPA defines separately from Customer Personal Data - may be used to train or tune models that deliver the Services (DPA 11.1), and this is not something you can opt out of (DPA 11.3). If you need this boundary set out for your own documentation, write to **privacy@emergent.sh**.\n</Note>\n","published_title":"AI & model training","title":"AI & model training","content":"## We do not train AI on your personal data\n\n<Callout type=\"success\" title=\"Your data is not training data\">\nEmergent does **not** use your Customer Personal Data to train, retrain, fine-tune or otherwise develop any AI or machine-learning model, and we **contractually prohibit** each sub-processor that provides AI models from doing so (DPA Section 12.1).\n</Callout>\n\nYour Customer Personal Data is processed **solely to provide, maintain, secure and support the Services** (DPA Section 12.2).\n\n## What the AI providers see\n\nEmergent uses third-party language models to power the agents. The providers in use, and the countries in which they process data, are listed at  **[app.emergent.sh/subprocessors](https://app.emergent.sh/subprocessors)**. They receive the prompt data needed to build your app: your prompts and instructions, conversation history, any files you upload, the code and files generated for you, and your database schema where it is part of the build context. Where you use those features, they also receive voice audio submitted for transcription and content entered by an agent operating a hosted browser. All of it is processed under the same DPA protections, and they are prohibited from training on it.\n\n<Note>\nService Data - operational data about how the Services are used, which the DPA defines separately from Customer Personal Data - may be used to train or tune models that deliver the Services (DPA 11.1), and this is not something you can opt out of (DPA 11.3). If you need this boundary set out for your own documentation, write to **privacy@emergent.sh**.\n</Note>\n","icon":"brain","description":"Emergent does not train AI models on your customer personal data (DPA 12.1).","order":304,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.833797+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"ed67749c-bd6e-42b8-8485-3893ea066f84","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"deletion-retention","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.942116+00:00","published_content":"## Deletion & retention\n\nThis page covers what happens to your data when you leave, and how to delete an account or a project.\n\n## When you stop being a customer\n\nWithin **45 days** of expiry or termination Emergent deletes your data in a step by step process and each step is irreversible. After 45 days, all your data is removed from Emergent's end. So requests for return of data is not possible.\n\n<Note>\nCancelling your subscription does not take your published apps offline - they keep running for as long as your account has credits to keep renewing them. Cancelling also does not delete your account or your data. Deleting your account is different: it deletes your data and shuts down your published apps - see the account deletion flow below.\n</Note>\n\n## Deleting an account vs a project\n\n<CardGroup cols={2}>\n<Card title=\"Delete a single project\" icon=\"folder-x\">\nOpen the project → **Settings → Danger Zone → Delete Project**. This is permanent, not reversible and a project's data will be deleted within 45 days from Emergent's end.\n</Card>\n<Card title=\"Delete your whole account\" icon=\"user-x\">\nUse the account deletion flow in **Account Settings**. This cancels your subscription and removes your published versions, and it is an irreversible action.\n</Card>\n</CardGroup>\n\n## Data in backups\n\nData held in routine back-ups or archives may not be capable of immediate deletion. It is **isolated, put beyond use and protected from any further processing** until it is deleted in line with our documented back-up cycle (DPA Section 14.4).\n\n## Written confirmation of deletion\n\nEmergent provides **written confirmation of deletion on request** (DPA Section 14.5).\n\n<Warning>\nA written confirmation is something you may file with a regulator, so it is prepared by our privacy team, not drafted ad hoc by support. Request it from **privacy@emergent.sh** and include your deadline.\n</Warning>\n","published_title":"Deletion & retention","title":"Deletion & retention","content":"## Deletion & retention\n\nThis page covers what happens to your data when you leave, and how to delete an account or a project.\n\n## When you stop being a customer\n\nWithin **45 days** of expiry or termination Emergent deletes your data in a step by step process and each step is irreversible. After 45 days, all your data is removed from Emergent's end. So requests for return of data is not possible.\n\n<Note>\nCancelling your subscription does not take your published apps offline - they keep running for as long as your account has credits to keep renewing them. Cancelling also does not delete your account or your data. Deleting your account is different: it deletes your data and shuts down your published apps - see the account deletion flow below.\n</Note>\n\n## Deleting an account vs a project\n\n<CardGroup cols={2}>\n<Card title=\"Delete a single project\" icon=\"folder-x\">\nOpen the project → **Settings → Danger Zone → Delete Project**. This is permanent, not reversible and a project's data will be deleted within 45 days from Emergent's end.\n</Card>\n<Card title=\"Delete your whole account\" icon=\"user-x\">\nUse the account deletion flow in **Account Settings**. This cancels your subscription and removes your published versions, and it is an irreversible action.\n</Card>\n</CardGroup>\n\n## Data in backups\n\nData held in routine back-ups or archives may not be capable of immediate deletion. It is **isolated, put beyond use and protected from any further processing** until it is deleted in line with our documented back-up cycle (DPA Section 14.4).\n\n## Written confirmation of deletion\n\nEmergent provides **written confirmation of deletion on request** (DPA Section 14.5).\n\n<Warning>\nA written confirmation is something you may file with a regulator, so it is prepared by our privacy team, not drafted ad hoc by support. Request it from **privacy@emergent.sh** and include your deadline.\n</Warning>\n","icon":"trash-2","description":"Leaving, deleting an account vs a project, backups, and written confirmation.","order":306,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.942116+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"eb5f3c27-ed53-4018-ae7d-c574c19feafe","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","slug":"security-breach-audit","parent_id":null,"created_at":"2026-09-08T10:09:57.787316+00:00","published_at":"2026-09-25T07:15:20.944634+00:00","published_content":"## Security, breach & audit\n\n## Breach notification\n\nEmergent notifies you **without undue delay and within 72 hours** of becoming aware of a personal data breach (DPA Section 10.1). The notification includes the nature of the breach, the categories and approximate numbers of data subjects and records affected, our contact point, the likely consequences, and the measures taken.\n\n## Technical & organisational measures\n\nAnnex 2 of the DPA sets out our technical and organisational measures, including:\n\n- Information-security policies and standards\n- Physical security\n- Incident response\n- Network security\n- Access control with periodic access reviews and offboarding deprovisioning\n- Anti-virus and malware controls\n- Personnel security training and a security-awareness programme\n- Subcontractor security no less onerous than the DPA's own safeguards\n- Business continuity and disaster-recovery planning\n\n<Note>\nAnnex 2 describes examples of safeguards and is not a representation that every control applies to every component of the Services. The full text is at **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**.\n</Note>\n\n## Audit & certification reports\n\nOn **written request, no more than once every twelve months**, Emergent makes available the information necessary to demonstrate compliance with the DPA, which can include certification reports or summaries (DPA Section 6.1). We also maintain an Article 30(2) record of processing.\n\n<Tip>\nRoute audit and due-diligence requests to **privacy@emergent.sh**.\n</Tip>\n\n## Encryption\n\nYour data is **encrypted in transit**, and your secrets (API keys and environment variables) are **encrypted at rest**. \n","published_title":"Security, breach & audit","title":"Security, breach & audit","content":"## Security, breach & audit\n\n## Breach notification\n\nEmergent notifies you **without undue delay and within 72 hours** of becoming aware of a personal data breach (DPA Section 10.1). The notification includes the nature of the breach, the categories and approximate numbers of data subjects and records affected, our contact point, the likely consequences, and the measures taken.\n\n## Technical & organisational measures\n\nAnnex 2 of the DPA sets out our technical and organisational measures, including:\n\n- Information-security policies and standards\n- Physical security\n- Incident response\n- Network security\n- Access control with periodic access reviews and offboarding deprovisioning\n- Anti-virus and malware controls\n- Personnel security training and a security-awareness programme\n- Subcontractor security no less onerous than the DPA's own safeguards\n- Business continuity and disaster-recovery planning\n\n<Note>\nAnnex 2 describes examples of safeguards and is not a representation that every control applies to every component of the Services. The full text is at **[app.emergent.sh/dpa](https://app.emergent.sh/dpa)**.\n</Note>\n\n## Audit & certification reports\n\nOn **written request, no more than once every twelve months**, Emergent makes available the information necessary to demonstrate compliance with the DPA, which can include certification reports or summaries (DPA Section 6.1). We also maintain an Article 30(2) record of processing.\n\n<Tip>\nRoute audit and due-diligence requests to **privacy@emergent.sh**.\n</Tip>\n\n## Encryption\n\nYour data is **encrypted in transit**, and your secrets (API keys and environment variables) are **encrypted at rest**. \n","icon":"shield-check","description":"Breach notification, security measures, audit requests and encryption.","order":308,"status":"published","deleted_at":null,"updated_at":"2026-09-25T07:15:20.944634+00:00","reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"1e0bc396-5d67-488f-ac65-2f66b58ea197","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Your data & ownership","slug":"your-data-ownership","content":"## Your data & ownership\n\nBeyond the GDPR/DPA specifics, here's what to expect about getting your code and data out.\n\n## Exporting your code & data\n\nYou can take your code and your data out of Emergent:\n\n- **Your code**: push it to GitHub with **Save → Save to GitHub** (Standard plan and above), then clone locally; or browse and copy files with the **Code** button in the top toolbar (all plans).\n- **Your database**: export it at any time with `mongodump` or MongoDB Compass, or as per-collection CSV from the Database Viewer. You may need to allowlist our IPs first ([app.emergent.sh/ip-addresses](https://app.emergent.sh/ip-addresses)). Full steps: see **[Database (MongoDB)](/database-mongodb)**.\n\n<Note>\n**Not included** in a code export: environment variables and secrets, database contents, and `node_modules`, handle those separately.\n</Note>\n\n## Backups & data safety\n\nEmergent keeps previous published versions of your app so you can roll back, and keeps routine back-ups of production data for platform resilience - backups are not a self-serve restore service. For your own safety net, export your own copy at any time using the methods above.\n\n## Who owns what you build\n\nYou do. Under our [Terms of Service](https://app.emergent.sh/terms-of-service) (Section 3.4), you retain all ownership rights to your Content - the code, projects, data and files you create through Emergent, including the applications you build. That covers AI-generated code as well: the Terms define Output (the code and other material the agents generate from your prompts) as part of your Content. Emergent owns only the platform itself - the underlying software, infrastructure, models and brand (Section 7.1).\n\nTwo practical notes from the Terms:\n\n- **No uniqueness guarantee**: output generated from similar prompts may resemble other users' output (Section 5.7) - your ownership of your app doesn't prevent someone else's similar prompt producing similar code.\n- **Subject to licenses**: your ownership sits alongside the operational licenses you grant Emergent in the Terms so the platform can host, build and serve your app.\n\n\n","order":311,"parent_id":null,"icon":"download","description":"Exporting your code and data, backups, and platform stability.","created_at":"2026-08-03T10:31:11.197154+00:00","updated_at":"2026-09-25T07:15:20.963466+00:00","published_at":"2026-09-25T07:15:20.963466+00:00","published_content":"## Your data & ownership\n\nBeyond the GDPR/DPA specifics, here's what to expect about getting your code and data out.\n\n## Exporting your code & data\n\nYou can take your code and your data out of Emergent:\n\n- **Your code**: push it to GitHub with **Save → Save to GitHub** (Standard plan and above), then clone locally; or browse and copy files with the **Code** button in the top toolbar (all plans).\n- **Your database**: export it at any time with `mongodump` or MongoDB Compass, or as per-collection CSV from the Database Viewer. You may need to allowlist our IPs first ([app.emergent.sh/ip-addresses](https://app.emergent.sh/ip-addresses)). Full steps: see **[Database (MongoDB)](/database-mongodb)**.\n\n<Note>\n**Not included** in a code export: environment variables and secrets, database contents, and `node_modules`, handle those separately.\n</Note>\n\n## Backups & data safety\n\nEmergent keeps previous published versions of your app so you can roll back, and keeps routine back-ups of production data for platform resilience - backups are not a self-serve restore service. For your own safety net, export your own copy at any time using the methods above.\n\n## Who owns what you build\n\nYou do. Under our [Terms of Service](https://app.emergent.sh/terms-of-service) (Section 3.4), you retain all ownership rights to your Content - the code, projects, data and files you create through Emergent, including the applications you build. That covers AI-generated code as well: the Terms define Output (the code and other material the agents generate from your prompts) as part of your Content. Emergent owns only the platform itself - the underlying software, infrastructure, models and brand (Section 7.1).\n\nTwo practical notes from the Terms:\n\n- **No uniqueness guarantee**: output generated from similar prompts may resemble other users' output (Section 5.7) - your ownership of your app doesn't prevent someone else's similar prompt producing similar code.\n- **Subject to licenses**: your ownership sits alongside the operational licenses you grant Emergent in the Terms so the platform can host, build and serve your app.\n\n\n","published_title":"Your data & ownership","status":"published","deleted_at":null,"reviewer_edited_at":null,"reviewer_edited_by":null},{"id":"7b42a3fc-2611-4361-bdbc-f61683a77d4c","project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","title":"Enable SEO: crawler pre-rendering","slug":"enable-seo-crawler-pre-rendering","order":"60","parent_id":null,"icon":"search","description":"How the Enable SEO crawler pre-rendering layer works, verifying it, and its limitations","content":"\nNew to SEO? Start with [Get found on Google](/get-found-on-google).\n\n## Why Google may see an empty page\n\nMost Emergent apps ship as a **single-page app (SPA)**: the HTML your server sends is a nearly empty shell, and your content is drawn by JavaScript once it loads in the browser. That works fine for people. It is a problem for search engines, because a crawler that reads only the HTML sees the same near-empty shell, and the same generic homepage title, on every route of your site.\n\n## Turn on Enable SEO\n\n**Enable SEO** switches on a pre-rendering layer that fixes this. You'll find it under:\n\n**Re-publish → Manage Publishing → Domain tab → Enable SEO**\n\nThe setting applies per published app and persists across re-publishes. Changing it takes effect within about a minute; you do not need to re-publish for the change itself to apply.\n\n<Callout type=\"note\" title=\"Current naming\">\nIf you have seen older guidance mention \"Publish / Re-publish → Domain\", that wording is out of date. Use the current path above.\n</Callout>\n\n### How it works: dynamic rendering\n\nWhen Enable SEO is on:\n\n<Steps>\n<Step title=\"A request arrives\">\nThe platform checks the request's User-Agent.\n</Step>\n<Step title=\"A crawler is detected\">\nIf it matches a known crawler (Googlebot, Bingbot, and other search and social crawlers), the request is handed to a headless Chrome browser that loads the page, waits for your JavaScript to finish, and captures the fully-rendered HTML.\n</Step>\n<Step title=\"The crawler gets real HTML\">\nIt receives that rendered HTML, with real per-route titles, meta tags, and structured data, instead of the shell.\n</Step>\n<Step title=\"The result is cached\">\nThe next crawler request hitting the same URL is served from the cache until it expires or you re-publish.\n</Step>\n</Steps>\n\nRegular visitors are unaffected; their browsers keep receiving the normal SPA, exactly as before. This technique is called **dynamic rendering**.\n\n## Should you turn it on?\n\n- **A standard Emergent app (React/SPA) you want indexed by Google:** **On.** Without it, crawlers see the homepage on every route.\n- **An app that already server-renders or pre-renders real HTML per route** (Next.js SSR/SSG, a committed pre-render build, or similar): **Off.** You do not need it, and leaving it on adds the limitations below.\n- **A private app, internal tool, or staging environment with nothing to index:** **Off.**\n- **You need crawlers to receive your redirects and 404s correctly** (site migration, retiring URLs, consolidating duplicates): **Off**, see \"Status codes\" below. This is the one case where the toggle can actively work against you.\n\n## How to check whether it's on\n\nRequest a deep route with a crawler User-Agent and look at the response headers:\n\n```bash\ncurl -sI -A \"Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)\" https://yourdomain.com/some/deep/route\n```\n\n- `x-rendered-by: crawler-renderer` : On, rendered fresh just now.\n- `x-rendered-by: crawler-cache` : On, served from the pre-render cache.\n- No `x-rendered-by` header : Off, the crawler gets the same response your visitors get.\n\nPre-rendered responses are sent with `cache-control: public, max-age=3600`. As a companion check, fetch the same URL **without** the crawler User-Agent and compare the two `<title>` tags. If the crawler version shows the correct page title and the plain version shows your homepage title, the layer is doing its job and your app is relying on it.\n\n## Limitations to know about\n\n### Status codes are not passed through (most important)\n\nWhen the pre-render layer answers a crawler, it returns `200 OK`, even for URLs your app answers with a redirect or an error. So if your origin returns `301` for a moved page, or `404` / `410` for a retired one, a crawler with SEO enabled still sees `200` plus rendered content. Consequences: redirects do not pass ranking signals (Google never sees the `301`), and retired pages stay indexed (a `410` crawlers never receive will not remove the URL). If you are migrating a site, consolidating duplicate URLs, or removing pages from the index, turn Enable SEO off for the duration. It is not currently possible to keep pre-rendering while preserving origin status codes.\n\n### Per-route meta tags can be captured too early\n\nThe renderer waits for the page to settle, then snapshots it. If a route sets its title and meta tags **after** an async data fetch (for example `<Helmet>` behind a loading skeleton), the snapshot can be taken before those tags apply, and the crawler gets your homepage title and canonical on that route. Routes that set meta tags synchronously on render are captured correctly, so the symptom is usually inconsistent across routes. **Fix:** set each route's `<title>`, canonical link, and OG tags on first render, outside any data-loading guard; fill in dynamic details once data arrives.\n\n### Not every bot is covered\n\nThe layer recognises major search and social crawlers. Less common bots, including some AI assistant and research crawlers, are not on the list and get the plain SPA shell even with the toggle on. If a specific crawler needs pre-rendered HTML, contact support with its exact User-Agent string. A validation tool fetching with its own User-Agent may report an empty shell while Googlebot itself is served correctly.\n\n### The cache holds for up to 30 days\n\nPre-rendered pages are cached per URL. Publishing new content does not immediately flush the cached copy for crawlers, and there is no self-serve purge; contact support to clear a cached page (for example a broken page captured during an outage). Turning the toggle off stops cached pages from being served but does not erase them; turning it back on can serve previously cached responses right away.\n\n<Callout type=\"note\" title=\"The toggle is the single source of truth\">\nIf support disables the layer during a ticket, switching **Enable SEO** back on in the Domain tab re-enables it. If your app was configured with SEO deliberately off, leave the toggle alone.\n</Callout>\n\n## Turning it off safely\n\nIf you are turning it off because you have your own pre-rendering, verify your own output is live first (build-time pre-render steps can fail silently while this layer covers for them):\n\n<Steps>\n<Step title=\"Request deep routes without a crawler\">\nRequest 2 to 3 deep routes without a crawler User-Agent.\n</Step>\n<Step title=\"Check the HTML\">\nConfirm the HTML already contains the correct per-route `<title>`, canonical link, and structured data.\n</Step>\n<Step title=\"Only then turn it off\">\nOnly if it does, turn the toggle off.\n</Step>\n<Step title=\"Re-check with a crawler\">\nBoth plain and crawler requests should now return the same real content, and `x-rendered-by` should be gone.\n</Step>\n</Steps>\n\nIf step 2 returns your homepage title or an empty shell, the platform layer is the only source of per-route content for search engines; turning it off typically loses indexed pages. Fix your own rendering first.\n\n## Is this cloaking? Will it hurt my rankings?\n\nNo. Cloaking means showing search engines different *content* to manipulate rankings. Dynamic rendering shows the **same content**, rendered server-side for clients that cannot run JavaScript well; Google documents it as an accepted workaround. If you are investigating a ranking drop where crawler and browser responses match, check instead for: bot protection challenging Googlebot; broken pages cached during a past outage; or the status-code behaviour above undermining redirects.\n\n<Callout type=\"note\" title=\"Getting help\">\nContact support with your custom domain and the affected routes, the `curl -I` output with and without the crawler User-Agent, and what you expected. Mention if you run your own pre-rendering, are mid-migration needing redirects honoured, or need a specific crawler User-Agent recognised.\n</Callout>\n","status":"published","published_at":"2026-10-05T14:16:54.057658+00:00","published_content":"\nNew to SEO? Start with [Get found on Google](/get-found-on-google).\n\n## Why Google may see an empty page\n\nMost Emergent apps ship as a **single-page app (SPA)**: the HTML your server sends is a nearly empty shell, and your content is drawn by JavaScript once it loads in the browser. That works fine for people. It is a problem for search engines, because a crawler that reads only the HTML sees the same near-empty shell, and the same generic homepage title, on every route of your site.\n\n## Turn on Enable SEO\n\n**Enable SEO** switches on a pre-rendering layer that fixes this. You'll find it under:\n\n**Re-publish → Manage Publishing → Domain tab → Enable SEO**\n\nThe setting applies per published app and persists across re-publishes. Changing it takes effect within about a minute; you do not need to re-publish for the change itself to apply.\n\n<Callout type=\"note\" title=\"Current naming\">\nIf you have seen older guidance mention \"Publish / Re-publish → Domain\", that wording is out of date. Use the current path above.\n</Callout>\n\n### How it works: dynamic rendering\n\nWhen Enable SEO is on:\n\n<Steps>\n<Step title=\"A request arrives\">\nThe platform checks the request's User-Agent.\n</Step>\n<Step title=\"A crawler is detected\">\nIf it matches a known crawler (Googlebot, Bingbot, and other search and social crawlers), the request is handed to a headless Chrome browser that loads the page, waits for your JavaScript to finish, and captures the fully-rendered HTML.\n</Step>\n<Step title=\"The crawler gets real HTML\">\nIt receives that rendered HTML, with real per-route titles, meta tags, and structured data, instead of the shell.\n</Step>\n<Step title=\"The result is cached\">\nThe next crawler request hitting the same URL is served from the cache until it expires or you re-publish.\n</Step>\n</Steps>\n\nRegular visitors are unaffected; their browsers keep receiving the normal SPA, exactly as before. This technique is called **dynamic rendering**.\n\n## Should you turn it on?\n\n- **A standard Emergent app (React/SPA) you want indexed by Google:** **On.** Without it, crawlers see the homepage on every route.\n- **An app that already server-renders or pre-renders real HTML per route** (Next.js SSR/SSG, a committed pre-render build, or similar): **Off.** You do not need it, and leaving it on adds the limitations below.\n- **A private app, internal tool, or staging environment with nothing to index:** **Off.**\n- **You need crawlers to receive your redirects and 404s correctly** (site migration, retiring URLs, consolidating duplicates): **Off**, see \"Status codes\" below. This is the one case where the toggle can actively work against you.\n\n## How to check whether it's on\n\nRequest a deep route with a crawler User-Agent and look at the response headers:\n\n```bash\ncurl -sI -A \"Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)\" https://yourdomain.com/some/deep/route\n```\n\n- `x-rendered-by: crawler-renderer` : On, rendered fresh just now.\n- `x-rendered-by: crawler-cache` : On, served from the pre-render cache.\n- No `x-rendered-by` header : Off, the crawler gets the same response your visitors get.\n\nPre-rendered responses are sent with `cache-control: public, max-age=3600`. As a companion check, fetch the same URL **without** the crawler User-Agent and compare the two `<title>` tags. If the crawler version shows the correct page title and the plain version shows your homepage title, the layer is doing its job and your app is relying on it.\n\n## Limitations to know about\n\n### Status codes are not passed through (most important)\n\nWhen the pre-render layer answers a crawler, it returns `200 OK`, even for URLs your app answers with a redirect or an error. So if your origin returns `301` for a moved page, or `404` / `410` for a retired one, a crawler with SEO enabled still sees `200` plus rendered content. Consequences: redirects do not pass ranking signals (Google never sees the `301`), and retired pages stay indexed (a `410` crawlers never receive will not remove the URL). If you are migrating a site, consolidating duplicate URLs, or removing pages from the index, turn Enable SEO off for the duration. It is not currently possible to keep pre-rendering while preserving origin status codes.\n\n### Per-route meta tags can be captured too early\n\nThe renderer waits for the page to settle, then snapshots it. If a route sets its title and meta tags **after** an async data fetch (for example `<Helmet>` behind a loading skeleton), the snapshot can be taken before those tags apply, and the crawler gets your homepage title and canonical on that route. Routes that set meta tags synchronously on render are captured correctly, so the symptom is usually inconsistent across routes. **Fix:** set each route's `<title>`, canonical link, and OG tags on first render, outside any data-loading guard; fill in dynamic details once data arrives.\n\n### Not every bot is covered\n\nThe layer recognises major search and social crawlers. Less common bots, including some AI assistant and research crawlers, are not on the list and get the plain SPA shell even with the toggle on. If a specific crawler needs pre-rendered HTML, contact support with its exact User-Agent string. A validation tool fetching with its own User-Agent may report an empty shell while Googlebot itself is served correctly.\n\n### The cache holds for up to 30 days\n\nPre-rendered pages are cached per URL. Publishing new content does not immediately flush the cached copy for crawlers, and there is no self-serve purge; contact support to clear a cached page (for example a broken page captured during an outage). Turning the toggle off stops cached pages from being served but does not erase them; turning it back on can serve previously cached responses right away.\n\n<Callout type=\"note\" title=\"The toggle is the single source of truth\">\nIf support disables the layer during a ticket, switching **Enable SEO** back on in the Domain tab re-enables it. If your app was configured with SEO deliberately off, leave the toggle alone.\n</Callout>\n\n## Turning it off safely\n\nIf you are turning it off because you have your own pre-rendering, verify your own output is live first (build-time pre-render steps can fail silently while this layer covers for them):\n\n<Steps>\n<Step title=\"Request deep routes without a crawler\">\nRequest 2 to 3 deep routes without a crawler User-Agent.\n</Step>\n<Step title=\"Check the HTML\">\nConfirm the HTML already contains the correct per-route `<title>`, canonical link, and structured data.\n</Step>\n<Step title=\"Only then turn it off\">\nOnly if it does, turn the toggle off.\n</Step>\n<Step title=\"Re-check with a crawler\">\nBoth plain and crawler requests should now return the same real content, and `x-rendered-by` should be gone.\n</Step>\n</Steps>\n\nIf step 2 returns your homepage title or an empty shell, the platform layer is the only source of per-route content for search engines; turning it off typically loses indexed pages. Fix your own rendering first.\n\n## Is this cloaking? Will it hurt my rankings?\n\nNo. Cloaking means showing search engines different *content* to manipulate rankings. Dynamic rendering shows the **same content**, rendered server-side for clients that cannot run JavaScript well; Google documents it as an accepted workaround. If you are investigating a ranking drop where crawler and browser responses match, check instead for: bot protection challenging Googlebot; broken pages cached during a past outage; or the status-code behaviour above undermining redirects.\n\n<Callout type=\"note\" title=\"Getting help\">\nContact support with your custom domain and the affected routes, the `curl -I` output with and without the crawler User-Agent, and what you expected. Mention if you run your own pre-rendering, are mid-migration needing redirects honoured, or need a specific crawler User-Agent recognised.\n</Callout>\n","published_title":"Enable SEO: crawler pre-rendering","created_at":"2026-09-15T10:05:47.871584+00:00","updated_at":"2026-10-05T14:16:54.057658+00:00","deleted_at":null,"reviewer_edited_at":null,"reviewer_edited_by":null}],"redirects":[{"project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","from_slug":"credit-expiry-recharging","created_at":"2026-09-17T13:06:12.628749+00:00","to_slug":"managing-credit-usage","updated_at":"2026-09-17T13:06:12.628749+00:00"},{"project_id":"d901b4ab-a271-4aff-b63a-bf92d73b9bb0","from_slug":"running-low-out-of-credits","created_at":"2026-09-17T13:06:12.628749+00:00","to_slug":"managing-credit-usage","updated_at":"2026-09-17T13:06:12.628749+00:00"}]}