For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/feature-flags.md (or send Accept: text/markdown).
Feature flags and announcements
Roll out dark, gate per workspace, and broadcast to members.
Beginner walkthrough
Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.
Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.
1. Sign in as a platform admin and open /admin/flags; create or select one test flag and set it explicitly to enabled, then disabled.
2. Refresh the product surface that reads the flag and confirm its presentation changes.
3. Roles and entitlements must still protect server actions when a flag is enabled. If the API remains accessible while disabled, add a server-side flag check where intended.
For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.
Configure flags in Admin
/admin/flags and feature-flags.ts provide the kit's flag management/evaluation path. Flag configuration belongs to the platform admin; a product UI can react to an allowed feature without gaining authority to change the flag.
Verify enabled and disabled behavior
Test defaults, missing flags, updates, role denial and flag-gated server actions. Preserve workspace access checks when adding rollout logic.
Setup and configuration
feature-flag-runtime resolves flags for a caller context: unconfigured flags default off, and per-flag overrides target specific workspaces or users. A missing flag can never silently enable a surface.
Platform announcements (announcement-actions) broadcast in-app notices through the same notification surface members already read — listActiveAnnouncements feeds the banner, dismissAnnouncementAction records the dismissal.
await isFeatureEnabled(flag, { workspaceId })
await resolveFeatureFlags(context)
listActiveAnnouncements()
dismissAnnouncementAction(formData)Implementation workflow
Ship code dark: merge behind a flag, enable it for your own workspace, then widen. Remove the flag once the surface is permanent — a stale flag is a second source of truth.
Check the flag at the server boundary AND the navigation: a hidden link with an open route is not a gated feature. Keep announcements off the transactional email path — they are product news, not receipts.
Verification and troubleshooting
Verify a disabled flag hides nav, route, and action end-to-end; an override resolves only for its target; and a cleared flag returns to the default. Test announcement delivery reaches the intended workspaces and that dismissal persists.