# Projects

Group related flags and environments into a durable application boundary.

A project contains flags, environments, evaluation keys, project settings, insights, and activity.
Use one when applications can share a flag namespace, environment model, and operational owner.

A project is an isolation boundary. It is not a temporary folder, deployment, release milestone, or
substitute for an organisation with independent membership and billing.

## Choose project boundaries

| Question       | Keep one project when…          | Split projects when…                       |
| -------------- | ------------------------------- | ------------------------------------------ |
| Flag namespace | Callers use the same decisions  | Keys would mean different things           |
| Environments   | Deployment stages align         | Services deploy through unrelated stages   |
| Credentials    | The same operators own rotation | Runtime access needs independent ownership |
| Lifecycle      | Releases are coordinated        | Products release and retire independently  |

A web application and API commonly share one project when both read `new-checkout`. An unrelated
internal tool should normally use another project, even if the same team maintains it.

Avoid one project per microservice by default. If services participate in the same product decision,
splitting them forces duplicated flags and makes coordinated rollout harder.

## Create a project

Owners and admins can create projects. Standard creation seeds `development`, `staging`, and
`production`. Choose an empty project when those names do not describe the real deployed boundaries.

After empty creation, open **Environments** and create at least one environment. Flag and runtime-key
creation remain disabled until an active environment exists.

Project slugs appear directly under the organisation URL. They use lowercase letters, numbers, and
dashes and reject reserved navigation names. Treat the slug as a durable link.

## Defaults and isolation

Organisation operational defaults provide cleanup and review thresholds. Project settings can
override them. These values influence review signals only; they never alter flag results.

Every flag needs an explicit configuration in each environment where it should resolve. Creating a
project or flag does not make one shared fallback available everywhere.

Keys never cross projects. A key bound to one project environment cannot select another project in a
URL or request body. If a caller sees a default unexpectedly, verify the key binding first.

## Work in a project

The project page is a flags-first surface. Use **Environments** for environment and key lifecycle,
**Insights** for hosted aggregates, **Activity** for changes, and **Settings** for identity and lifecycle.

Members can change flags, targeting, environments, and evaluation keys. Project identity, archive,
transfer, and deletion require elevated authority. Viewers cannot mutate project state.

## Archive, transfer, and delete

Archive hides a project from ordinary work while preserving history. Restore it before making normal
changes. Archive provides a reversible checkpoint and should precede permanent deletion.

A source owner can transfer a project only to an organisation where they are owner or admin. Active
runtime and client keys are rebound to the destination.

Project-scoped management keys in the source organisation are revoked. If the destination uses the
same slug, FeatureGate adds a numeric suffix rather than overwriting another project.

Permanent deletion is owner-only and requires archive first. Historical activity and API usage retain
their recorded organisation attribution.

## Common problems

- **Flag creation is disabled:** create or restore an active environment first.
- **A key cannot evaluate a flag:** confirm the key and flag share a project and environment.
- **Transferred automation stopped:** replace source project-scoped management keys.
- **The old URL fails:** open the organisation landing page and use the current slug.
- **An archived project is missing:** enable archived discovery and restore it before editing.

See [Project lifecycle and transfer](/docs/administration/project-lifecycle) before moving or deleting
production resources.