feat: use lifecycles API

frontend/.claude/context/testing-against-pr-backend.md

@@ -0,0 +1,72 @@
+# Testing the Frontend Against an Unmerged Backend PR
+
+When a backend PR adds or changes API behaviour, you can run that exact backend
+locally — without checking out or building the API — and point your local
+frontend dev server at it. CI publishes a Docker image for every PR.
+
+## Where the images live
+
+Every PR's CI builds and **pushes** multi-arch (amd64 + arm64) images to GHCR,
+tagged `pr-<number>`. They are **public** — no `docker login` needed.
+
+| Image | Tag | Contents |
+| --- | --- | --- |
+| `ghcr.io/flagsmith/flagsmith` | `pr-<number>` | Unified image — API + bundled frontend, serves on `:8000` |
+| `ghcr.io/flagsmith/flagsmith-api` | `pr-<number>` | API only |
+
+Use the **unified** image with the repo's root `docker-compose.yml`, which is
+already wired for it (Postgres, migrations, API, task processor).
+
+Confirm an image exists before relying on it:
+
+```bash
+docker manifest inspect ghcr.io/flagsmith/flagsmith:pr-<number> >/dev/null && echo pullable
+```
+
+## Run a PR backend + local frontend
+
+From the repo root, create a one-off compose override that swaps the three
+`flagsmith` services onto the PR image (the root compose hardcodes the image, so
+an override file is the clean way to repoint it):
+
+```bash
+cat > docker-compose.pr.yml <<'EOF'
+services:
+  migrate-db:
+    image: ghcr.io/flagsmith/flagsmith:pr-<number>
+  flagsmith:
+    image: ghcr.io/flagsmith/flagsmith:pr-<number>
+  flagsmith-task-processor:
+    image: ghcr.io/flagsmith/flagsmith:pr-<number>
+EOF
+
+docker compose -f docker-compose.yml -f docker-compose.pr.yml pull
+docker compose -f docker-compose.yml -f docker-compose.pr.yml up
+```
+
+The API comes up on `localhost:8000`. Then run the frontend against it:
+
+```bash
+cd frontend
+ENV=local npm run dev   # dev server on :3000, talks to the API on :8000
+```
+
+`docker-compose.pr.yml` is throwaway — delete it (or keep it git-ignored) when
+done. To switch PRs, change the tag and re-run `pull` + `up`.
+
+## Notes / gotchas
+
+- **Flagsmith-on-Flagsmith gates.** Backend features are often gated by an
+  OpenFeature flag (e.g. `feature_lifecycle`). The flag's default for a
+  self-hosted/local run comes from the baked-in
+  `api/integrations/flagsmith/data/environment.json`. Check it's enabled there;
+  if not, the gated endpoints/fields won't appear.
+- **Data, not just code.** Endpoints may need seeded data to return anything
+  meaningful (e.g. code references, stale tags, usage). The image gives you the
+  behaviour; you still have to create the data through the UI/API.
+- **Inspect what the PR actually built.** Job logs show the pushed tag:
+  `gh run view --job <id> --log | grep -i 'tags:'`. The `pr-<number>` convention
+  is stable, but the logs are the source of truth.
+- **Contract-checking without running.** To verify the frontend matches a
+  backend PR's contract, read its diff directly instead of (or before) running:
+  `gh api repos/Flagsmith/flagsmith/contents/<path>?ref=<pr-head-branch> --jq .content | base64 -d`.

frontend/CLAUDE.md

@@ -33,6 +33,7 @@ For detailed guidance on specific topics:
 - **Quick Start**: `.claude/context/quick-reference.md` - Common tasks, commands, patterns
 - **API Integration**: `.claude/context/api-integration.md` - Adding endpoints, RTK Query (required reading for API work)
 - **Backend**: `.claude/context/backend-integration.md` - Finding endpoints, backend structure
+- **Testing vs PR backend**: `.claude/context/testing-against-pr-backend.md` - Run an unmerged backend PR's Docker image locally and point the dev server at it
 - **UI Patterns**: `.claude/context/ui-patterns.md` - Tables, tabs, modals, confirmations (required reading for UI work)
 - **Feature Flags**: `.claude/context/feature-flags/` - Using Flagsmith flags (optional, only when requested)
 - **Code Patterns**: `.claude/context/patterns/` - Complete examples, best practices

frontend/common/lifecycleEnvironmentSlice.ts

@@ -0,0 +1,26 @@
+import { createSlice, PayloadAction } from '@reduxjs/toolkit'
+
+type LifecycleEnvironmentState = {
+  // Maps a project id to the environment id selected for lifecycle analysis.
+  byProject: Record<number, number>
+}
+
+const initialState: LifecycleEnvironmentState = {
+  byProject: {},
+}
+
+const lifecycleEnvironmentSlice = createSlice({
+  initialState,
+  name: 'lifecycleEnvironment',
+  reducers: {
+    setLifecycleEnvironment(
+      state,
+      action: PayloadAction<{ projectId: number; environmentId: number }>,
+    ) {
+      state.byProject[action.payload.projectId] = action.payload.environmentId
+    },
+  },
+})
+
+export const { setLifecycleEnvironment } = lifecycleEnvironmentSlice.actions
+export default lifecycleEnvironmentSlice.reducer

frontend/common/services/useProjectFlag.ts

@@ -132,6 +132,18 @@ export const projectFlagService = service
         }),
       }),
 
+      getLifecycleStatusCounts: builder.query<
+        Res['lifecycleStatusCounts'],
+        Req['getLifecycleStatusCounts']
+      >({
+        providesTags: (_res, _meta, req) => [
+          { id: req?.environment, type: 'ProjectFlag' },
+        ],
+        query: ({ environment }) => ({
+          url: `environments/${environment}/feature-lifecycle-counts/`,
+        }),
+      }),
+
       getProjectFlag: builder.query<Res['projectFlag'], Req['getProjectFlag']>({
         providesTags: (res) => [{ id: res?.id, type: 'ProjectFlag' }],
         query: (query: Req['getProjectFlag']) => ({
@@ -284,6 +296,7 @@ export const {
   useAddFlagOwnersMutation,
   useCreateProjectFlagMutation,
   useGetFeatureListQuery,
+  useGetLifecycleStatusCountsQuery,
   useGetProjectFlagQuery,
   useGetProjectFlagsQuery,
   useRemoveFlagGroupOwnersMutation,

frontend/common/store.ts

@@ -14,10 +14,12 @@ import storage from 'redux-persist/lib/storage'
 import { Persistor } from 'redux-persist/es/types'
 import { service } from './service'
 import selectedOrganisationReducer from './selectedOrganisationSlice'
+import lifecycleEnvironmentReducer from './lifecycleEnvironmentSlice'
 // END OF IMPORTS
 const createStore = () => {
   const reducer = combineReducers({
     [service.reducerPath]: service.reducer,
+    lifecycleEnvironment: lifecycleEnvironmentReducer,
     selectedOrganisation: selectedOrganisationReducer,
     // END OF REDUCERS
   })

frontend/common/types/requests.ts

@@ -32,6 +32,7 @@ import {
   FlagsmithValue,
   TagStrategy,
   FeatureType,
+  LifecycleStage,
 } from './responses'
 import { UtmsType } from './utms'
 
@@ -395,6 +396,10 @@ export type Req = {
     group_owners?: number[]
     sort_field?: string
     sort_direction?: SortOrder
+    lifecycle_stage?: LifecycleStage
+  }
+  getLifecycleStatusCounts: {
+    environment: number
   }
   getProjectFlag: { project: number; id: number }
   getRolesPermissionUsers: { organisation_id: number; role_id: number }

frontend/common/types/responses.ts

@@ -816,8 +816,19 @@ export type ProjectFlag = {
     last_successful_repository_scanned_at: string
     last_feature_found_at: string
   }[]
+  lifecycle_stage?: LifecycleStage | null
 }
 
+export type LifecycleStage =
+  | 'new'
+  | 'live'
+  | 'permanent'
+  | 'stale'
+  | 'needs_monitoring'
+  | 'to_remove'
+
+export type LifecycleStatusCounts = Record<LifecycleStage, number>
+
 export type FeatureListProviderData = {
   projectFlags: ProjectFlag[] | null
   environmentFlags: Record<number, FeatureState> | undefined
@@ -1344,6 +1355,7 @@ export type Res = {
   rolePermission: PagedResponse<RolePermission>
   projectFlags: PagedResponse<ProjectFlag>
   projectFlag: ProjectFlag
+  lifecycleStatusCounts: LifecycleStatusCounts
   identityFeatureStatesAll: IdentityFeatureState[]
   createRolesPermissionUsers: RolePermissionUser
   rolesPermissionUsers: PagedResponse<RolePermissionUser>

frontend/web/components/import-export/FeatureImport.tsx

@@ -139,34 +139,36 @@ const FeatureExport: FC<FeatureExportType> = ({ projectId }) => {
     if (fileData) {
       const createdDate = new Date().toISOString()
       const existingFlags =
-        !!fileData &&
-        !!currentFeatureStates &&
-        currentProjectflags?.map((projectFlag, i) => {
-          const featureState = currentFeatureStates[projectFlag.id]
-          const importItem = fileData.find((v) => v.name === projectFlag.name)
-          let newValue = featureState.value
-          let newEnabled = featureState.enabled
+        fileData && currentFeatureStates && currentProjectflags
+          ? currentProjectflags.map((projectFlag, i) => {
+              const featureState = currentFeatureStates[projectFlag.id]
+              const importItem = fileData.find(
+                (v) => v.name === projectFlag.name,
+              )
+              let newValue = featureState.value
+              let newEnabled = featureState.enabled
 
-          // Overwrite destructive replaces existing feature values
-          if (strategy === 'OVERWRITE_DESTRUCTIVE' && importItem) {
-            // For the targeted environment it will use the imported feature values
-            if (environment === previewEnvironment) {
-              newEnabled = importItem.enabled
-              newValue = importItem.value
-            } else {
-              // For every other environment the features are overwritten with the imported default enabled state and value
-              newEnabled = importItem.default_enabled
-              newValue = importItem.initial_value
-            }
-          }
-          return {
-            ...projectFlag,
-            created_date: projectFlag.created_date,
-            default_enabled: newEnabled,
-            id: i,
-            initial_value: newValue,
-          }
-        })
+              // Overwrite destructive replaces existing feature values
+              if (strategy === 'OVERWRITE_DESTRUCTIVE' && importItem) {
+                // For the targeted environment it will use the imported feature values
+                if (environment === previewEnvironment) {
+                  newEnabled = importItem.enabled
+                  newValue = importItem.value
+                } else {
+                  // For every other environment the features are overwritten with the imported default enabled state and value
+                  newEnabled = importItem.default_enabled
+                  newValue = importItem.initial_value
+                }
+              }
+              return {
+                ...projectFlag,
+                created_date: projectFlag.created_date,
+                default_enabled: newEnabled,
+                id: i,
+                initial_value: newValue,
+              }
+            })
+          : []
 
       const fileFlags = fileData
         .filter((v) => {