diff --git a/docs/guides/faq.mdx b/docs/guides/faq.mdx
new file mode 100644
index 00000000..81890681
--- /dev/null
+++ b/docs/guides/faq.mdx
@@ -0,0 +1,439 @@
+# FAQ
+
+
+
+### Getting Started
+
+
+
+Do I need a Reddit API key, client ID, or client secret to build with Devvit?
+
+No. If you are building a Devvit app, you do not need to create a traditional Reddit app at [`reddit.com/prefs/apps`](https://www.reddit.com/prefs/apps) or manage API keys yourself.
+
+Instead, start from the [App quickstart](../quickstart/quickstart.md) or create a project at [developers.reddit.com/new](https://developers.reddit.com/new). During setup, you sign in with your Reddit account and connect it to Reddit developers. Devvit then handles authentication for your app.
+
+To read or write Reddit content from a Devvit app, enable the Reddit capability described in the [Reddit API Overview](../capabilities/server/reddit-api.mdx).
+
+:::note
+If you are building an external script, bot, or website outside Devvit, that is a different authentication flow from the one documented here.
+:::
+
+
+
+
+
+Where do I start building a Devvit app?
+
+The fastest path is the [App quickstart](../quickstart/quickstart.md), which walks you through creating a project, connecting your Reddit account, and starting a playtest environment.
+
+If you already know which kind of app you want to build, you can also start with:
+
+- [Quickstart for Games](../quickstart/quickstart.md)
+- [Quickstart for Mod Tools](../quickstart/quickstart-mod-tool.md)
+- [Quickstart for Unity](../quickstart/quickstart-unity.mdx)
+- [Quickstart for GameMaker](../quickstart/quickstart-gamemaker.mdx)
+
+
+
+
+
+How do I log in, and how do I know I am authenticated?
+
+Use the CLI to sign in with your Reddit account:
+
+```bash
+npx devvit login
+```
+
+To confirm which account is currently authenticated, run:
+
+```bash
+npx devvit whoami
+```
+
+After login, Devvit stores your access token locally at `~/.devvit/token` and refreshes it automatically while you use the CLI.
+
+For command details, see the [`devvit login`](./tools/devvit_cli.mdx#devvit-login) and [`devvit whoami`](./tools/devvit_cli.mdx#devvit-whoami) sections of the CLI reference.
+
+
+
+### Building And Testing
+
+
+
+Can I test locally without uploading to Reddit?
+
+Not completely. Devvit apps run against Reddit, so the normal development flow uses a playtest subreddit instead of a fully local backend-only workflow.
+
+The quickstart uses `npm run dev`, which starts a Devvit playtest session for you. If you need more control over that flow, see [Playtest](./tools/playtest.md).
+
+If you are wondering why a purely local setup is not enough, the quickstart calls this out directly: backend calls do not work when you test the app only locally.
+
+
+
+
+
+Why does npm run dev, playtest, upload, or install fail?
+
+Most development errors fall into a few buckets:
+
+- Authentication: make sure you are logged in with `npx devvit login`, then verify the current account with `npx devvit whoami`.
+- Build output mismatch: if Devvit cannot find `config.server.entry`, check that your built server file matches the path in `devvit.json`, and that your server build outputs a CommonJS bundle. The best references are [Devvit configuration](../capabilities/devvit-web/devvit_web_configuration.md) and [Vite](./tools/vite.mdx).
+- Config validation: if `devvit.json` complains about invalid fields, extra properties, or settings shapes, validate it against the schema and configuration rules in [Devvit configuration](../capabilities/devvit-web/devvit_web_configuration.md).
+- Fetch or domain errors: if fetch is disabled or a domain is rejected, configure `permissions.http` correctly and review the rules in [HTTP fetch](../capabilities/server/http-fetch.mdx).
+- Runtime failures during playtest or install: use [Playtest](./tools/playtest.md) and [Logs and Debugging](./tools/logs.md) together so you can see the failing endpoint or trigger.
+
+One other common gotcha: Devvit projects use `vite build --watch` rather than a normal `vite dev` server. The [Vite guide](./tools/vite.mdx) explains the expected setup.
+
+
+
+
+
+How do I update the Devvit CLI?
+
+Prefer updating the project-local CLI dependency instead of relying on a global install. The current docs recommend updating `devvit` in your project, then running `npx devvit update app` so your `@devvit` packages match the CLI.
+
+For the current commands and workflow, see [Devvit CLI](./tools/devvit_cli.mdx), [Optimizing performance](../capabilities/blocks/optimize_performance.md), and the update notes in [Changelog](../changelog.md).
+
+
+
+
+
+How do I update my app version?
+
+Updating the CLI and publishing a new app version are separate steps. Your app version changes when you publish: `npx devvit publish` creates the next launch version, and you can control that with `--bump` or `--version` as described in [Launch your app](./launch/launch-guide.md).
+
+After that, the subreddit still needs to be on the version you want installed. In other words, publishing a new version is not the same as updating every subreddit automatically. Use [`devvit install`](./tools/devvit_cli.mdx#devvit-install) or open your app in the [App Directory](https://developers.reddit.com/apps/) and, under **Installed in communities**, use the blue **Update** button for the subreddit that is out of date.
+
+
+
+
+
+What is the difference between npx devvit upload and npx devvit publish?
+
+Use `npx devvit upload` when you want a private uploaded build for yourself, and use `npx devvit publish` when you are ready to submit a version for launch review. In practice, playtest is still the normal dev loop, `upload` is useful for a private installable build, and `publish` is the launch step documented in [Launch your app](./launch/launch-guide.md).
+
+For command syntax, see [Devvit CLI](./tools/devvit_cli.mdx). For the review and launch flow, see [Launch your app](./launch/launch-guide.md).
+
+
+
+
+
+What should I do after playtest when I am ready to launch?
+
+Before launch, make sure the app is stable across mobile and web, test with multiple accounts, and add an installer-friendly `README.md`. Then follow the publish flow in [Launch your app](./launch/launch-guide.md).
+
+If you are just ending a playtest session, remember that the latest playtest install remains in place until you change installs. [Playtest](./tools/playtest.md) and [`devvit install`](./tools/devvit_cli.mdx#devvit-install) cover that handoff.
+
+
+
+
+
+How do I install my app on another subreddit?
+
+If you moderate the destination subreddit, use [`devvit install`](./tools/devvit_cli.mdx#devvit-install) to install a specific app or version on that community. That is the direct CLI path when you want to move beyond the playtest subreddit or test on another subreddit you control.
+
+If the goal is broader distribution, follow [Launch your app](./launch/launch-guide.md) so moderators can install the approved app in the appropriate way for its visibility level.
+
+
+
+
+
+What is the difference between unlisted and public apps?
+
+Published apps are unlisted by default. That is usually the right fit for games and single-community tools. If you want your app to appear in the App Directory so any moderator can install it, use `npx devvit publish --public` and follow the listing guidance in [Launch your app](./launch/launch-guide.md).
+
+Public apps should look launch-ready: the launch docs call for a detailed installer-facing `README.md`, and game launch guidance expects a custom launch or first screen rather than a rough default experience.
+
+
+
+### App Features
+
+
+
+What is an interactive post in Devvit?
+
+An interactive post is a Reddit post created for an app experience rather than a plain text-only post. In the current docs, that means creating the post with `reddit.submitCustomPost()` and defining how it launches through entry points, launch screens, and optional `postData`. See [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx) and [Creating a custom post](../capabilities/creating_custom_post.md).
+
+
+
+
+
+Why is my post just text instead of an interactive app post?
+
+If you call `submitPost()` with normal `text`, you are creating a regular Reddit post. To create an interactive app post, use `submitCustomPost()` and point it at your configured entry point instead. The [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx) is the clearest starting point for that distinction.
+
+
+
+
+
+What is Devvit Web?
+
+Devvit Web is the current client/server app model for building Devvit apps with standard web tools such as React, Phaser, or Three.js. The docs describe it as a normal web app plus server endpoints plus `devvit.json` configuration, with Reddit capabilities split between client APIs, server APIs, and config. See [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx).
+
+
+
+
+
+Should I use Devvit Web or Devvit Blocks for a new game?
+
+Use Devvit Web for new games. The current docs say Devvit Web has reached feature parity with Blocks for new apps, strongly recommend Devvit Web for all new apps, and note that `Devvit.addCustomPostType()` is deprecated and new apps using it will be rejected during review. The clearest sources are [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx) and [Changelog](../changelog.md).
+
+
+
+
+
+Can I combine Devvit Blocks and Devvit Web?
+
+Legacy and partially migrated apps can still mix pieces while they transition, and the migration guides explicitly say apps can be partially migrated. But for new game-style interactive posts, the better direction is to move the experience to Devvit Web instead of designing a new Blocks-plus-Web architecture around deprecated custom post APIs. See [Migrating from useWebView to Devvit Web](./migrate/inline-web-view.md) and [Migrating Blocks/Mod Tools to Devvit Web](./migrate/devvit-singleton.md).
+
+
+
+
+
+How do I migrate from Blocks or useWebView to Devvit Web?
+
+There are separate migration guides depending on what you are starting from: Blocks/Mod Tools, `useWebView`, and Devvit Web experimental. In all cases, the main shift is toward `devvit.json`, explicit client/server folders, and direct server endpoints instead of older message-passing or singleton-based setup. Start with [Blocks/Mod Tools to Devvit Web](./migrate/devvit-singleton.md), [useWebView to Devvit Web](./migrate/inline-web-view.md), or [Devvit Web Experimental to Devvit Web](./migrate/devvit-web-experimental.md).
+
+
+
+
+
+Where do I customize the first screen or launch screen?
+
+For current Devvit Web apps, customize the first screen through your `post.entrypoints` in `devvit.json` and the HTML, CSS, and client code for those entry files. The main references are [Launch overview](../capabilities/server/launch_screen_and_entry_points/launch_overview.mdx), [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md), and [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md).
+
+
+
+
+
+Should I use the legacy splash field or HTML launch entry points?
+
+Prefer HTML launch entry points for new work. The older `splash` parameter is still documented, but the migration guide marks it as deprecated in favor of entrypoint-based launch screens and `entry` selection in `submitCustomPost()`. If you are updating an older app or wondering why splash changes are confusing, start with [Migrating from Splash Screens](../capabilities/server/launch_screen_and_entry_points/splash_migration.mdx).
+
+
+
+
+
+How do I handle scrolling and touch gestures in inline vs expanded mode?
+
+Treat inline and expanded mode differently. Inline should avoid scroll traps and heavy gesture hijacking so users can still scroll past the post, while expanded is the right place for richer touch interaction and more space.
+
+There is no single canonical viewport size for all devices. Design responsively, test in [UI Simulator](./tools/ui_simulator.mdx), and use the current launch-mode docs for inline vs expanded behavior in [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md) and [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md).
+
+
+
+
+
+How do I add images that ship with my app?
+
+Put static images in the root `assets/` directory when they should ship with the app version, such as logos, backgrounds, or other bundled art. The docs cover both `` usage and `context.assets.getURL()` in [App image assets](../capabilities/blocks/app_image_assets.md).
+
+
+
+
+
+How do user image uploads work in Devvit?
+
+The simplest path is a form field with `type: 'image'`, which returns a Reddit-hosted image URL when the user submits it. For custom flows such as screenshots or generated images, send the data to your server and upload it with [Media uploads](../capabilities/server/media-uploads.mdx).
+
+See [Forms](../capabilities/client/forms.mdx) and [Media uploads](../capabilities/server/media-uploads.mdx) for the supported formats and size limits.
+
+
+
+
+
+What image URLs can I use in a Devvit app?
+
+The documented display paths are bundled asset filenames, Reddit-hosted URLs, and SVG data URLs, depending on the UI surface. If your source image lives somewhere else on the web, do not assume you can hotlink it directly into the UI. Upload it first so Reddit hosts the image, then use the returned URL. See [Image](../blocks/image.mdx), [App image assets](../capabilities/blocks/app_image_assets.md), and [Media uploads](../capabilities/server/media-uploads.mdx).
+
+
+
+
+
+What is postData, and when should I use it instead of Redis?
+
+Use `postData` for small shared JSON attached to a single post, such as lightweight game state or configuration that all viewers need to read. The docs cap it at 2 KB per post and explicitly recommend [Redis](../capabilities/server/redis.mdx) for larger or more persistent data patterns.
+
+
+
+
+
+How do I access or update postData?
+
+Set `postData` when creating the post, then read it from `context.postData` on either the client or server side. To update it later, fetch the post and call `setPostData()`. The important gotcha is that `setPostData()` replaces the whole object, so merge existing fields first. See [Post data](../capabilities/server/post-data.mdx).
+
+
+
+
+
+How do I build a leaderboard with Redis?
+
+The standard Devvit pattern is to build leaderboards with Redis sorted sets. Use [Redis](../capabilities/server/redis.mdx) for score storage and ranking, use [Scheduler](../capabilities/server/scheduler.mdx) for daily or periodic resets, and prefer realtime updates over constant polling when you need a live leaderboard.
+
+Keep the FAQ answer short: Redis is the right storage layer, but the exact schema depends on whether you need daily, weekly, or all-time rankings. The best starting points are [Redis](../capabilities/server/redis.mdx) and the leaderboard/performance guidance in [Optimizing performance](../capabilities/blocks/optimize_performance.md).
+
+
+
+
+
+Can a menu action create a new post?
+
+Yes. Define the menu item in `devvit.json`, implement the server endpoint it calls, and create the post from that route. The pattern is documented across [Menu actions](../capabilities/client/menu-actions.mdx) and [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx).
+
+
+
+
+
+How do I automate daily or scheduled game posts?
+
+Use [Scheduler](../capabilities/server/scheduler.mdx) for cron-style recurring jobs or one-off jobs declared in `devvit.json`, then handle the matching `/internal/...` endpoint in your server code. The scheduler docs explain the plumbing; the post creation step still uses the normal Reddit APIs such as `submitCustomPost()`.
+
+
+
+
+
+How do I post or comment as the user instead of the app?
+
+Add the required `permissions.reddit.asUser` entries in `devvit.json`, then call the supported Reddit APIs with `runAs: 'USER'`. The main doc for this is [User Actions](../capabilities/server/userActions.mdx), which also explains the review requirements, explicit opt-in rules, and `userGeneratedContent` expectations.
+
+
+
+
+
+Why does runAs: 'USER' still post as the app during playtest?
+
+Before the app version is approved, user actions are not enabled for everyone. During playtest or other unapproved versions, `runAs: 'USER'` falls back to the app account for most users, while actions taken by the app owner are attributed to the owner's username. After publishing and approval, it operates on behalf of the user for all users. See [User Actions](../capabilities/server/userActions.mdx).
+
+
+
+
+
+How do I set or update user flair and post flair?
+
+Devvit supports both user flair and post flair through the Reddit API client.
+
+- For a new post, use the submit options documented in [CommonSubmitPostOptions](../api/redditapi/models/type-aliases/CommonSubmitPostOptions.md), including `flairId` or `flairText`.
+- For an existing post, use the flair methods on [RedditAPIClient](../api/redditapi/RedditAPIClient/classes/RedditAPIClient.md), such as `setPostFlair()` and `removePostFlair()`.
+- For a user, use `setUserFlair()`, `removeUserFlair()`, or `setUserFlairBatch()` on the same client.
+
+If you are reading flair back from a post, note that post flair and author flair are different fields. The [Post](../api/redditapi/models/classes/Post.md) model exposes `flair` for the post and `authorFlair` for the post author.
+
+If you need to react to flair changes, Devvit documents an [`onPostFlairUpdate`](../capabilities/server/triggers.mdx) trigger for post flair changes. Also note that the [Devvit test tool](./tools/devvit_test.mdx) does not yet support the Flair service.
+
+
+
+
+
+How do I get a user's username or snoovatar?
+
+If you only need the current user's name, prefer `getCurrentUsername()`. The [performance guide](../capabilities/blocks/optimize_performance.md) recommends this over fetching the full user object.
+
+If you need more profile information, use `getCurrentUser()` from the [Reddit API client](../api/redditapi/RedditAPIClient/classes/RedditAPIClient.md). To get a snoovatar URL, use `reddit.getSnoovatarUrl(username)` or `user.getSnoovatarUrl()` on the [User](../api/redditapi/models/classes/User.md) model.
+
+Some handlers also expose experimental identity fields such as `username` and `snoovatar` on [BaseContext](../api/public-api/type-aliases/BaseContext.md), but the Reddit client methods are the clearest documented path.
+
+If you are building with Devvit Blocks, the API also exposes an [`avatar`](../api/public-api/@devvit/namespaces/Devvit/namespaces/Blocks/type-aliases/AvatarProps.md) component that renders from a `thingId`.
+
+
+
+
+
+How do I handle external links in Devvit?
+
+Use Devvit navigation APIs to open links rather than treating this like external fetch. For app navigation, see [Navigation](../capabilities/client/navigation.mdx), which covers `navigateTo` and the confirmation flow for external URLs.
+
+If you actually need remote data or remote media, that is a different path: use [HTTP fetch](../capabilities/server/http-fetch.mdx) for approved server-side fetches, and [Media uploads](../capabilities/server/media-uploads.mdx) when you need a Reddit-hosted media URL.
+
+
+
+### Limits And Policies
+
+
+
+What are the main storage, payload, and rate limits?
+
+There is no single limits page today, but these are the most commonly referenced numbers in the docs:
+
+- [Redis](../capabilities/server/redis.mdx): 500 MB max storage per installation, 5 MB max request size, and 40,000 max commands per second.
+- [Devvit Web](../capabilities/devvit-web/devvit_web_overview.mdx): 30 second max request time, 4 MB max payload size, and 10 MB max response size.
+- [Post data](../capabilities/server/post-data.mdx): 2 KB per post.
+- [Settings and secrets](../capabilities/server/settings-and-secrets.mdx): 2 KB per setting value.
+- [Realtime](../capabilities/realtime/realtime_in_devvit_blocks.md): 1 MB maximum message payload and 100 messages per second per installation.
+- [Scheduler](../capabilities/server/scheduler.mdx): up to 10 live recurring actions per installation, plus `runJob()` limits documented on that page.
+
+If you need data to survive app updates, do not rely on browser `localStorage`. The [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx) recommends Redis for persistent storage across versions.
+
+
+
+
+
+What screen sizes should I design for?
+
+The docs do not publish one fixed pixel size for every device or view mode. Instead, build responsive layouts and test them across the views supported by the [UI Simulator](./tools/ui_simulator.mdx): mobile, desktop, and fullscreen.
+
+For Devvit Web, inline and expanded mode behave differently: expanded is the larger experience, with more room for rich interaction, while inline should stay lightweight and feed-friendly. For Devvit Blocks, layout sizing is based on [device-independent pixels and percentages](../blocks/overview.mdx), not a single universal viewport.
+
+If you are tuning layout behavior, start with mobile-first assumptions and validate in the simulator before hard-coding dimensions. The best references are [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md), [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md), and [UI Simulator](./tools/ui_simulator.mdx).
+
+
+
+
+
+Can I build NSFW games or apps with Devvit?
+
+There is no separate NSFW platform guide in these docs, so the main source of truth is [Devvit Rules](../devvit_rules.md) plus Reddit's linked platform policies.
+
+The rules explicitly require labels or age-gating before exposing users to graphic, sexually explicit, or otherwise mature content. Static assets and uploaded media are also subject to the same safety checks and policy review described in [App image assets](../capabilities/blocks/app_image_assets.md) and [Media uploads](../capabilities/server/media-uploads.mdx).
+
+If your app idea depends on adult content or NSFW communities, review those rules first and get clarification in the [Devvit Discord](https://developers.reddit.com/discord) before you ship.
+
+
+
+### Help And Next Steps
+
+
+
+Where do I go for help if I am stuck?
+
+For help from the Devvit team and community:
+
+- Join the [Devvit Discord](https://developers.reddit.com/discord)
+- Ask in [`r/Devvit`](https://www.reddit.com/r/Devvit)
+- File bugs or feature requests in the [public issues tracker](https://github.com/reddit/devvit/issues)
+
+
+
+
+
+How do I uninstall or remove a Devvit app from a subreddit?
+
+Use the CLI to inspect installs and uninstall from a subreddit. The current docs point to `list installs` and `uninstall` in [Devvit CLI](./tools/devvit_cli.mdx).
+
+There is also a manual path in the [App Directory](https://developers.reddit.com/apps/). Open your app there, then either use **Installed in communities** to select a subreddit and choose **Remove from community**, or scroll to the bottom of the app page and use **Archive** if you want to archive the app itself.
+
+Be careful: uninstalling from a subreddit can remove that installation's stored data and settings. See [Mod resources](./best-practices/mod_resources.md) for the current warning about uninstall data loss. The current docs are much clearer about uninstalling from a subreddit than they are about a full developer-side "delete this app from the platform" flow.
+
+
+
+
+
+What is Devvit MCP and how do I set it up?
+
+Devvit MCP is the bridge used by supported coding tools and agents to search Devvit docs and, in some setups, work with Devvit workflows from your editor. The setup docs live in [Using AI Tools](./ai/ai.md).
+
+If you are configuring Cursor, VS Code Copilot, Claude Code, or Claude Desktop, start there instead of duplicating the JSON in this FAQ. Keep this page as the pointer, and use the AI tools guide for the exact MCP config and supported tools.
+
+
+
+
+
+What should I read next?
+
+- To understand Devvit's built-in Reddit access, read the [Reddit API Overview](../capabilities/server/reddit-api.mdx)
+- To learn the CLI commands you will use most often, read [Devvit CLI](./tools/devvit_cli.mdx)
+- To develop against a subreddit and inspect logs, read [Playtest](./tools/playtest.md) and [Logs and Debugging](./tools/logs.md)
+
+
+
+
diff --git a/sidebars.ts b/sidebars.ts
index 49619feb..3eef0480 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -317,6 +317,11 @@ const sidebars: SidebarsConfig = {
label: "Using AI Tools",
id: "guides/ai/ai",
},
+ {
+ type: "doc",
+ label: "FAQ",
+ id: "guides/faq",
+ },
{
type: "html",
value: "
",
diff --git a/src/css/custom.css b/src/css/custom.css
index f8395f73..d3ceba33 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -278,3 +278,77 @@ div.themed-col:hover {
background: var(--ifm-color-primary);
border-bottom: none;
}
+
+/* FAQ accordion styling */
+.faq-page details.alert.alert--info {
+ --ifm-alert-background-color: transparent;
+ --ifm-alert-background-color-highlight: transparent;
+ --ifm-alert-border-color: var(--ifm-toc-border-color);
+ --ifm-alert-foreground-color: var(--ifm-font-color-base);
+ --ifm-link-color: #ff4500;
+ --docusaurus-details-decoration-color: var(--ifm-toc-border-color);
+ margin: 0 0 0.75rem;
+ border: 1px solid var(--ifm-toc-border-color);
+ border-radius: 8px;
+ background: transparent;
+ box-shadow: none;
+ color: var(--ifm-font-color-base);
+}
+
+.faq-page details.alert.alert--info > summary {
+ cursor: pointer;
+ color: var(--ifm-link-color);
+ background: transparent !important;
+ padding: 0.85rem 1rem !important;
+ font-weight: 600;
+ list-style: none;
+ text-decoration: none !important;
+ margin: 0;
+}
+
+.faq-page details.alert.alert--info > summary::before {
+ content: none !important;
+ display: none !important;
+}
+
+.faq-page details.alert.alert--info > summary::marker {
+ content: "";
+}
+
+.faq-page details.alert.alert--info > summary::-webkit-details-marker {
+ display: none;
+}
+
+.faq-page details.alert.alert--info > summary:hover,
+.faq-page details.alert.alert--info[open] > summary {
+ color: var(--ifm-link-color);
+ background: transparent !important;
+ text-decoration: none !important;
+}
+
+.faq-page details.alert.alert--info > summary code {
+ color: inherit;
+}
+
+.faq-page details.alert.alert--info > summary:focus {
+ outline: none;
+}
+
+.faq-page details.alert.alert--info > summary:focus-visible {
+ outline: 2px solid var(--ifm-link-color);
+ outline-offset: 2px;
+ border-radius: 6px;
+}
+
+.faq-page details.alert.alert--info [class*="collapsibleContent"] {
+ border-top: 1px solid var(--ifm-toc-border-color) !important;
+ margin-top: 0.75rem;
+ padding-top: 0.75rem;
+}
+
+.faq-page details.alert.alert--info a,
+.faq-page details.alert.alert--info a:hover,
+.faq-page details.alert.alert--info a:visited,
+.faq-page details.alert.alert--info a:active {
+ color: var(--ifm-link-color);
+}
diff --git a/versioned_docs/version-0.12/guides/faq.mdx b/versioned_docs/version-0.12/guides/faq.mdx
new file mode 100644
index 00000000..81890681
--- /dev/null
+++ b/versioned_docs/version-0.12/guides/faq.mdx
@@ -0,0 +1,439 @@
+# FAQ
+
+
+
+### Getting Started
+
+
+
+Do I need a Reddit API key, client ID, or client secret to build with Devvit?
+
+No. If you are building a Devvit app, you do not need to create a traditional Reddit app at [`reddit.com/prefs/apps`](https://www.reddit.com/prefs/apps) or manage API keys yourself.
+
+Instead, start from the [App quickstart](../quickstart/quickstart.md) or create a project at [developers.reddit.com/new](https://developers.reddit.com/new). During setup, you sign in with your Reddit account and connect it to Reddit developers. Devvit then handles authentication for your app.
+
+To read or write Reddit content from a Devvit app, enable the Reddit capability described in the [Reddit API Overview](../capabilities/server/reddit-api.mdx).
+
+:::note
+If you are building an external script, bot, or website outside Devvit, that is a different authentication flow from the one documented here.
+:::
+
+
+
+
+
+Where do I start building a Devvit app?
+
+The fastest path is the [App quickstart](../quickstart/quickstart.md), which walks you through creating a project, connecting your Reddit account, and starting a playtest environment.
+
+If you already know which kind of app you want to build, you can also start with:
+
+- [Quickstart for Games](../quickstart/quickstart.md)
+- [Quickstart for Mod Tools](../quickstart/quickstart-mod-tool.md)
+- [Quickstart for Unity](../quickstart/quickstart-unity.mdx)
+- [Quickstart for GameMaker](../quickstart/quickstart-gamemaker.mdx)
+
+
+
+
+
+How do I log in, and how do I know I am authenticated?
+
+Use the CLI to sign in with your Reddit account:
+
+```bash
+npx devvit login
+```
+
+To confirm which account is currently authenticated, run:
+
+```bash
+npx devvit whoami
+```
+
+After login, Devvit stores your access token locally at `~/.devvit/token` and refreshes it automatically while you use the CLI.
+
+For command details, see the [`devvit login`](./tools/devvit_cli.mdx#devvit-login) and [`devvit whoami`](./tools/devvit_cli.mdx#devvit-whoami) sections of the CLI reference.
+
+
+
+### Building And Testing
+
+
+
+Can I test locally without uploading to Reddit?
+
+Not completely. Devvit apps run against Reddit, so the normal development flow uses a playtest subreddit instead of a fully local backend-only workflow.
+
+The quickstart uses `npm run dev`, which starts a Devvit playtest session for you. If you need more control over that flow, see [Playtest](./tools/playtest.md).
+
+If you are wondering why a purely local setup is not enough, the quickstart calls this out directly: backend calls do not work when you test the app only locally.
+
+
+
+
+
+Why does npm run dev, playtest, upload, or install fail?
+
+Most development errors fall into a few buckets:
+
+- Authentication: make sure you are logged in with `npx devvit login`, then verify the current account with `npx devvit whoami`.
+- Build output mismatch: if Devvit cannot find `config.server.entry`, check that your built server file matches the path in `devvit.json`, and that your server build outputs a CommonJS bundle. The best references are [Devvit configuration](../capabilities/devvit-web/devvit_web_configuration.md) and [Vite](./tools/vite.mdx).
+- Config validation: if `devvit.json` complains about invalid fields, extra properties, or settings shapes, validate it against the schema and configuration rules in [Devvit configuration](../capabilities/devvit-web/devvit_web_configuration.md).
+- Fetch or domain errors: if fetch is disabled or a domain is rejected, configure `permissions.http` correctly and review the rules in [HTTP fetch](../capabilities/server/http-fetch.mdx).
+- Runtime failures during playtest or install: use [Playtest](./tools/playtest.md) and [Logs and Debugging](./tools/logs.md) together so you can see the failing endpoint or trigger.
+
+One other common gotcha: Devvit projects use `vite build --watch` rather than a normal `vite dev` server. The [Vite guide](./tools/vite.mdx) explains the expected setup.
+
+
+
+
+
+How do I update the Devvit CLI?
+
+Prefer updating the project-local CLI dependency instead of relying on a global install. The current docs recommend updating `devvit` in your project, then running `npx devvit update app` so your `@devvit` packages match the CLI.
+
+For the current commands and workflow, see [Devvit CLI](./tools/devvit_cli.mdx), [Optimizing performance](../capabilities/blocks/optimize_performance.md), and the update notes in [Changelog](../changelog.md).
+
+
+
+
+
+How do I update my app version?
+
+Updating the CLI and publishing a new app version are separate steps. Your app version changes when you publish: `npx devvit publish` creates the next launch version, and you can control that with `--bump` or `--version` as described in [Launch your app](./launch/launch-guide.md).
+
+After that, the subreddit still needs to be on the version you want installed. In other words, publishing a new version is not the same as updating every subreddit automatically. Use [`devvit install`](./tools/devvit_cli.mdx#devvit-install) or open your app in the [App Directory](https://developers.reddit.com/apps/) and, under **Installed in communities**, use the blue **Update** button for the subreddit that is out of date.
+
+
+
+
+
+What is the difference between npx devvit upload and npx devvit publish?
+
+Use `npx devvit upload` when you want a private uploaded build for yourself, and use `npx devvit publish` when you are ready to submit a version for launch review. In practice, playtest is still the normal dev loop, `upload` is useful for a private installable build, and `publish` is the launch step documented in [Launch your app](./launch/launch-guide.md).
+
+For command syntax, see [Devvit CLI](./tools/devvit_cli.mdx). For the review and launch flow, see [Launch your app](./launch/launch-guide.md).
+
+
+
+
+
+What should I do after playtest when I am ready to launch?
+
+Before launch, make sure the app is stable across mobile and web, test with multiple accounts, and add an installer-friendly `README.md`. Then follow the publish flow in [Launch your app](./launch/launch-guide.md).
+
+If you are just ending a playtest session, remember that the latest playtest install remains in place until you change installs. [Playtest](./tools/playtest.md) and [`devvit install`](./tools/devvit_cli.mdx#devvit-install) cover that handoff.
+
+
+
+
+
+How do I install my app on another subreddit?
+
+If you moderate the destination subreddit, use [`devvit install`](./tools/devvit_cli.mdx#devvit-install) to install a specific app or version on that community. That is the direct CLI path when you want to move beyond the playtest subreddit or test on another subreddit you control.
+
+If the goal is broader distribution, follow [Launch your app](./launch/launch-guide.md) so moderators can install the approved app in the appropriate way for its visibility level.
+
+
+
+
+
+What is the difference between unlisted and public apps?
+
+Published apps are unlisted by default. That is usually the right fit for games and single-community tools. If you want your app to appear in the App Directory so any moderator can install it, use `npx devvit publish --public` and follow the listing guidance in [Launch your app](./launch/launch-guide.md).
+
+Public apps should look launch-ready: the launch docs call for a detailed installer-facing `README.md`, and game launch guidance expects a custom launch or first screen rather than a rough default experience.
+
+
+
+### App Features
+
+
+
+What is an interactive post in Devvit?
+
+An interactive post is a Reddit post created for an app experience rather than a plain text-only post. In the current docs, that means creating the post with `reddit.submitCustomPost()` and defining how it launches through entry points, launch screens, and optional `postData`. See [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx) and [Creating a custom post](../capabilities/creating_custom_post.md).
+
+
+
+
+
+Why is my post just text instead of an interactive app post?
+
+If you call `submitPost()` with normal `text`, you are creating a regular Reddit post. To create an interactive app post, use `submitCustomPost()` and point it at your configured entry point instead. The [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx) is the clearest starting point for that distinction.
+
+
+
+
+
+What is Devvit Web?
+
+Devvit Web is the current client/server app model for building Devvit apps with standard web tools such as React, Phaser, or Three.js. The docs describe it as a normal web app plus server endpoints plus `devvit.json` configuration, with Reddit capabilities split between client APIs, server APIs, and config. See [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx).
+
+
+
+
+
+Should I use Devvit Web or Devvit Blocks for a new game?
+
+Use Devvit Web for new games. The current docs say Devvit Web has reached feature parity with Blocks for new apps, strongly recommend Devvit Web for all new apps, and note that `Devvit.addCustomPostType()` is deprecated and new apps using it will be rejected during review. The clearest sources are [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx) and [Changelog](../changelog.md).
+
+
+
+
+
+Can I combine Devvit Blocks and Devvit Web?
+
+Legacy and partially migrated apps can still mix pieces while they transition, and the migration guides explicitly say apps can be partially migrated. But for new game-style interactive posts, the better direction is to move the experience to Devvit Web instead of designing a new Blocks-plus-Web architecture around deprecated custom post APIs. See [Migrating from useWebView to Devvit Web](./migrate/inline-web-view.md) and [Migrating Blocks/Mod Tools to Devvit Web](./migrate/devvit-singleton.md).
+
+
+
+
+
+How do I migrate from Blocks or useWebView to Devvit Web?
+
+There are separate migration guides depending on what you are starting from: Blocks/Mod Tools, `useWebView`, and Devvit Web experimental. In all cases, the main shift is toward `devvit.json`, explicit client/server folders, and direct server endpoints instead of older message-passing or singleton-based setup. Start with [Blocks/Mod Tools to Devvit Web](./migrate/devvit-singleton.md), [useWebView to Devvit Web](./migrate/inline-web-view.md), or [Devvit Web Experimental to Devvit Web](./migrate/devvit-web-experimental.md).
+
+
+
+
+
+Where do I customize the first screen or launch screen?
+
+For current Devvit Web apps, customize the first screen through your `post.entrypoints` in `devvit.json` and the HTML, CSS, and client code for those entry files. The main references are [Launch overview](../capabilities/server/launch_screen_and_entry_points/launch_overview.mdx), [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md), and [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md).
+
+
+
+
+
+Should I use the legacy splash field or HTML launch entry points?
+
+Prefer HTML launch entry points for new work. The older `splash` parameter is still documented, but the migration guide marks it as deprecated in favor of entrypoint-based launch screens and `entry` selection in `submitCustomPost()`. If you are updating an older app or wondering why splash changes are confusing, start with [Migrating from Splash Screens](../capabilities/server/launch_screen_and_entry_points/splash_migration.mdx).
+
+
+
+
+
+How do I handle scrolling and touch gestures in inline vs expanded mode?
+
+Treat inline and expanded mode differently. Inline should avoid scroll traps and heavy gesture hijacking so users can still scroll past the post, while expanded is the right place for richer touch interaction and more space.
+
+There is no single canonical viewport size for all devices. Design responsively, test in [UI Simulator](./tools/ui_simulator.mdx), and use the current launch-mode docs for inline vs expanded behavior in [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md) and [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md).
+
+
+
+
+
+How do I add images that ship with my app?
+
+Put static images in the root `assets/` directory when they should ship with the app version, such as logos, backgrounds, or other bundled art. The docs cover both `` usage and `context.assets.getURL()` in [App image assets](../capabilities/blocks/app_image_assets.md).
+
+
+
+
+
+How do user image uploads work in Devvit?
+
+The simplest path is a form field with `type: 'image'`, which returns a Reddit-hosted image URL when the user submits it. For custom flows such as screenshots or generated images, send the data to your server and upload it with [Media uploads](../capabilities/server/media-uploads.mdx).
+
+See [Forms](../capabilities/client/forms.mdx) and [Media uploads](../capabilities/server/media-uploads.mdx) for the supported formats and size limits.
+
+
+
+
+
+What image URLs can I use in a Devvit app?
+
+The documented display paths are bundled asset filenames, Reddit-hosted URLs, and SVG data URLs, depending on the UI surface. If your source image lives somewhere else on the web, do not assume you can hotlink it directly into the UI. Upload it first so Reddit hosts the image, then use the returned URL. See [Image](../blocks/image.mdx), [App image assets](../capabilities/blocks/app_image_assets.md), and [Media uploads](../capabilities/server/media-uploads.mdx).
+
+
+
+
+
+What is postData, and when should I use it instead of Redis?
+
+Use `postData` for small shared JSON attached to a single post, such as lightweight game state or configuration that all viewers need to read. The docs cap it at 2 KB per post and explicitly recommend [Redis](../capabilities/server/redis.mdx) for larger or more persistent data patterns.
+
+
+
+
+
+How do I access or update postData?
+
+Set `postData` when creating the post, then read it from `context.postData` on either the client or server side. To update it later, fetch the post and call `setPostData()`. The important gotcha is that `setPostData()` replaces the whole object, so merge existing fields first. See [Post data](../capabilities/server/post-data.mdx).
+
+
+
+
+
+How do I build a leaderboard with Redis?
+
+The standard Devvit pattern is to build leaderboards with Redis sorted sets. Use [Redis](../capabilities/server/redis.mdx) for score storage and ranking, use [Scheduler](../capabilities/server/scheduler.mdx) for daily or periodic resets, and prefer realtime updates over constant polling when you need a live leaderboard.
+
+Keep the FAQ answer short: Redis is the right storage layer, but the exact schema depends on whether you need daily, weekly, or all-time rankings. The best starting points are [Redis](../capabilities/server/redis.mdx) and the leaderboard/performance guidance in [Optimizing performance](../capabilities/blocks/optimize_performance.md).
+
+
+
+
+
+Can a menu action create a new post?
+
+Yes. Define the menu item in `devvit.json`, implement the server endpoint it calls, and create the post from that route. The pattern is documented across [Menu actions](../capabilities/client/menu-actions.mdx) and [Interactive posts overview](../capabilities/interactive-posts/interactive_posts_overview.mdx).
+
+
+
+
+
+How do I automate daily or scheduled game posts?
+
+Use [Scheduler](../capabilities/server/scheduler.mdx) for cron-style recurring jobs or one-off jobs declared in `devvit.json`, then handle the matching `/internal/...` endpoint in your server code. The scheduler docs explain the plumbing; the post creation step still uses the normal Reddit APIs such as `submitCustomPost()`.
+
+
+
+
+
+How do I post or comment as the user instead of the app?
+
+Add the required `permissions.reddit.asUser` entries in `devvit.json`, then call the supported Reddit APIs with `runAs: 'USER'`. The main doc for this is [User Actions](../capabilities/server/userActions.mdx), which also explains the review requirements, explicit opt-in rules, and `userGeneratedContent` expectations.
+
+
+
+
+
+Why does runAs: 'USER' still post as the app during playtest?
+
+Before the app version is approved, user actions are not enabled for everyone. During playtest or other unapproved versions, `runAs: 'USER'` falls back to the app account for most users, while actions taken by the app owner are attributed to the owner's username. After publishing and approval, it operates on behalf of the user for all users. See [User Actions](../capabilities/server/userActions.mdx).
+
+
+
+
+
+How do I set or update user flair and post flair?
+
+Devvit supports both user flair and post flair through the Reddit API client.
+
+- For a new post, use the submit options documented in [CommonSubmitPostOptions](../api/redditapi/models/type-aliases/CommonSubmitPostOptions.md), including `flairId` or `flairText`.
+- For an existing post, use the flair methods on [RedditAPIClient](../api/redditapi/RedditAPIClient/classes/RedditAPIClient.md), such as `setPostFlair()` and `removePostFlair()`.
+- For a user, use `setUserFlair()`, `removeUserFlair()`, or `setUserFlairBatch()` on the same client.
+
+If you are reading flair back from a post, note that post flair and author flair are different fields. The [Post](../api/redditapi/models/classes/Post.md) model exposes `flair` for the post and `authorFlair` for the post author.
+
+If you need to react to flair changes, Devvit documents an [`onPostFlairUpdate`](../capabilities/server/triggers.mdx) trigger for post flair changes. Also note that the [Devvit test tool](./tools/devvit_test.mdx) does not yet support the Flair service.
+
+
+
+
+
+How do I get a user's username or snoovatar?
+
+If you only need the current user's name, prefer `getCurrentUsername()`. The [performance guide](../capabilities/blocks/optimize_performance.md) recommends this over fetching the full user object.
+
+If you need more profile information, use `getCurrentUser()` from the [Reddit API client](../api/redditapi/RedditAPIClient/classes/RedditAPIClient.md). To get a snoovatar URL, use `reddit.getSnoovatarUrl(username)` or `user.getSnoovatarUrl()` on the [User](../api/redditapi/models/classes/User.md) model.
+
+Some handlers also expose experimental identity fields such as `username` and `snoovatar` on [BaseContext](../api/public-api/type-aliases/BaseContext.md), but the Reddit client methods are the clearest documented path.
+
+If you are building with Devvit Blocks, the API also exposes an [`avatar`](../api/public-api/@devvit/namespaces/Devvit/namespaces/Blocks/type-aliases/AvatarProps.md) component that renders from a `thingId`.
+
+
+
+
+
+How do I handle external links in Devvit?
+
+Use Devvit navigation APIs to open links rather than treating this like external fetch. For app navigation, see [Navigation](../capabilities/client/navigation.mdx), which covers `navigateTo` and the confirmation flow for external URLs.
+
+If you actually need remote data or remote media, that is a different path: use [HTTP fetch](../capabilities/server/http-fetch.mdx) for approved server-side fetches, and [Media uploads](../capabilities/server/media-uploads.mdx) when you need a Reddit-hosted media URL.
+
+
+
+### Limits And Policies
+
+
+
+What are the main storage, payload, and rate limits?
+
+There is no single limits page today, but these are the most commonly referenced numbers in the docs:
+
+- [Redis](../capabilities/server/redis.mdx): 500 MB max storage per installation, 5 MB max request size, and 40,000 max commands per second.
+- [Devvit Web](../capabilities/devvit-web/devvit_web_overview.mdx): 30 second max request time, 4 MB max payload size, and 10 MB max response size.
+- [Post data](../capabilities/server/post-data.mdx): 2 KB per post.
+- [Settings and secrets](../capabilities/server/settings-and-secrets.mdx): 2 KB per setting value.
+- [Realtime](../capabilities/realtime/realtime_in_devvit_blocks.md): 1 MB maximum message payload and 100 messages per second per installation.
+- [Scheduler](../capabilities/server/scheduler.mdx): up to 10 live recurring actions per installation, plus `runJob()` limits documented on that page.
+
+If you need data to survive app updates, do not rely on browser `localStorage`. The [Devvit Web overview](../capabilities/devvit-web/devvit_web_overview.mdx) recommends Redis for persistent storage across versions.
+
+
+
+
+
+What screen sizes should I design for?
+
+The docs do not publish one fixed pixel size for every device or view mode. Instead, build responsive layouts and test them across the views supported by the [UI Simulator](./tools/ui_simulator.mdx): mobile, desktop, and fullscreen.
+
+For Devvit Web, inline and expanded mode behave differently: expanded is the larger experience, with more room for rich interaction, while inline should stay lightweight and feed-friendly. For Devvit Blocks, layout sizing is based on [device-independent pixels and percentages](../blocks/overview.mdx), not a single universal viewport.
+
+If you are tuning layout behavior, start with mobile-first assumptions and validate in the simulator before hard-coding dimensions. The best references are [View modes and entry points](../capabilities/server/launch_screen_and_entry_points/view_modes_entry_points.md), [Launch screen customization](../capabilities/server/launch_screen_and_entry_points/launch_screen_customization.md), and [UI Simulator](./tools/ui_simulator.mdx).
+
+
+
+
+
+Can I build NSFW games or apps with Devvit?
+
+There is no separate NSFW platform guide in these docs, so the main source of truth is [Devvit Rules](../devvit_rules.md) plus Reddit's linked platform policies.
+
+The rules explicitly require labels or age-gating before exposing users to graphic, sexually explicit, or otherwise mature content. Static assets and uploaded media are also subject to the same safety checks and policy review described in [App image assets](../capabilities/blocks/app_image_assets.md) and [Media uploads](../capabilities/server/media-uploads.mdx).
+
+If your app idea depends on adult content or NSFW communities, review those rules first and get clarification in the [Devvit Discord](https://developers.reddit.com/discord) before you ship.
+
+
+
+### Help And Next Steps
+
+
+
+Where do I go for help if I am stuck?
+
+For help from the Devvit team and community:
+
+- Join the [Devvit Discord](https://developers.reddit.com/discord)
+- Ask in [`r/Devvit`](https://www.reddit.com/r/Devvit)
+- File bugs or feature requests in the [public issues tracker](https://github.com/reddit/devvit/issues)
+
+
+
+
+
+How do I uninstall or remove a Devvit app from a subreddit?
+
+Use the CLI to inspect installs and uninstall from a subreddit. The current docs point to `list installs` and `uninstall` in [Devvit CLI](./tools/devvit_cli.mdx).
+
+There is also a manual path in the [App Directory](https://developers.reddit.com/apps/). Open your app there, then either use **Installed in communities** to select a subreddit and choose **Remove from community**, or scroll to the bottom of the app page and use **Archive** if you want to archive the app itself.
+
+Be careful: uninstalling from a subreddit can remove that installation's stored data and settings. See [Mod resources](./best-practices/mod_resources.md) for the current warning about uninstall data loss. The current docs are much clearer about uninstalling from a subreddit than they are about a full developer-side "delete this app from the platform" flow.
+
+
+
+
+
+What is Devvit MCP and how do I set it up?
+
+Devvit MCP is the bridge used by supported coding tools and agents to search Devvit docs and, in some setups, work with Devvit workflows from your editor. The setup docs live in [Using AI Tools](./ai/ai.md).
+
+If you are configuring Cursor, VS Code Copilot, Claude Code, or Claude Desktop, start there instead of duplicating the JSON in this FAQ. Keep this page as the pointer, and use the AI tools guide for the exact MCP config and supported tools.
+
+
+
+
+
+What should I read next?
+
+- To understand Devvit's built-in Reddit access, read the [Reddit API Overview](../capabilities/server/reddit-api.mdx)
+- To learn the CLI commands you will use most often, read [Devvit CLI](./tools/devvit_cli.mdx)
+- To develop against a subreddit and inspect logs, read [Playtest](./tools/playtest.md) and [Logs and Debugging](./tools/logs.md)
+
+
+
+
diff --git a/versioned_sidebars/version-0.12-sidebars.json b/versioned_sidebars/version-0.12-sidebars.json
index fa8c94f9..b72dfc6b 100644
--- a/versioned_sidebars/version-0.12-sidebars.json
+++ b/versioned_sidebars/version-0.12-sidebars.json
@@ -306,6 +306,11 @@
"label": "Using AI Tools",
"id": "guides/ai/ai"
},
+ {
+ "type": "doc",
+ "label": "FAQ",
+ "id": "guides/faq"
+ },
{
"type": "html",
"value": "
",