docs: align lifecycle definitions, consolidate to single source, drop em dashes

- Rewrite the canonical User Lifecycle rules in wallet-profiles.mdx to match
  the hardcoded defaults: New = first seen within 30d; Returning = first seen
  >30d ago, active recently, <5 active days, no 30+ day gap; Power User = >30d
  ago and 5+ of last 30 days; Resurrected = re-engaged after a 30+ day gap;
  Churned = last seen >30d ago. Stages computed against a reference date.
- Consolidate the duplicated definitions in overview, metrics, catalog,
  dau-tracking, and retention down to short summaries that link back to the
  single authoritative section.
- Remove all em dashes across the docs (.mdx and api/openapi.json).
- Add CLAUDE.md with writing-style and single-source-of-truth guidance.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yosriady

CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+Guidance for AI agents working in this repository (the Formo docs site, built with Mintlify).
+
+## Writing style
+
+- **Never use em dashes (`—`).** Rewrite the sentence instead: use a colon for a term/definition, a semicolon or period to split clauses, parentheses for an aside, or a comma. This applies to all content: `.mdx` pages, the OpenAPI spec (`api/openapi.json`), summaries, and titles.
+- En dashes (`–`) are also discouraged; use "to" for ranges (e.g. "5 to 10").
+- The arrow character `→` is fine where it represents a flow or a UI path (e.g. "Settings → Lifecycle", "page → connect → swap").
+
+## Single source of truth
+
+Define each concept once and link to it elsewhere rather than restating the details (which drift out of sync).
+
+- **User lifecycle stages** (New, Returning, Power User, Resurrected, Churned): the authoritative definition with exact rules and thresholds lives in `features/wallet-intelligence/wallet-profiles.mdx` (`#user-lifecycle`). Other pages should give a brief, contextual mention and link to it. The SQL-oriented restatement in `data/catalog.mdx` is the one allowed exception, since it serves query writers in-context.
+
+## API reference
+
+`api/openapi.json` is the source spec that generates the API reference pages. Keep it valid JSON; descriptions render as published docs, so apply the writing-style rules above to them too.

api/openapi.json

@@ -2,10 +2,10 @@
 title: "Analytics"
 sidebarTitle: "Analytics"
 icon: chart-mixed
-description: "Run Formo's pre-built analytics pipes — KPIs, funnels, retention, revenue, and top-N breakdowns — directly from the terminal, without writing SQL."
+description: "Run Formo's pre-built analytics pipes (KPIs, funnels, retention, revenue, and top-N breakdowns) directly from the terminal, without writing SQL."
 ---
 
-The `formo analytics` command exposes Formo's pre-built analytics pipes — the same data that powers the Formo dashboard — as terminal commands. Each pipe is a subcommand: `formo analytics <pipe>`.
+The `formo analytics` command exposes Formo's pre-built analytics pipes (the same data that powers the Formo dashboard) as terminal commands. Each pipe is a subcommand: `formo analytics <pipe>`.
 
 <Note>
 Requires `query:read` scope on your API key.
@@ -45,7 +45,7 @@ Requires `query:read` scope on your API key.
 | `--params` | `string` | ❌ | JSON object of pipe-specific params merged into the query |
 
 <Note>
-`--params` may **not** set `date_from`/`date_to`/`filters` — use the dedicated
+`--params` may **not** set `date_from`/`date_to`/`filters`; use the dedicated
 `--date-from`/`--date-to`/`--filters` flags for those. Object/array values in
 `--params` are JSON-encoded automatically (e.g. `funnel`'s `steps`).
 </Note>
@@ -61,8 +61,8 @@ Some pipes take additional, pipe-specific parameters. Pass them as a JSON object
 | Pipe | Key params |
 |------|------------|
 | `kpis`, `revenue_overview` | `group_by`, `limit`, `include_previous_period` |
-| `funnel` | `steps` (required — JSON array of `{type,event,name,filters?}`), `window_seconds`, `funnel_type`, `breakdown` |
-| `flow` | `start_step` (required — JSON `{type,event,resolved_event,...}`), `end_step`, `global_filters`, `window_seconds`, `max_steps` |
+| `funnel` | `steps` (required, a JSON array of `{type,event,name,filters?}`), `window_seconds`, `funnel_type`, `breakdown` |
+| `flow` | `start_step` (required, a JSON `{type,event,resolved_event,...}`), `end_step`, `global_filters`, `window_seconds`, `max_steps` |
 | `retention` | `id_type`, `event_type`, `event_name`, `min_users` |
 | `revenue_timeseries` | `address` (required) |
 | `revenue_by_metric`, `volume_by_metric`, `top_sources` | `metric_column`, `limit`, `offset` |

cli/analytics.mdx

@@ -134,9 +134,9 @@ The `--conditions` option accepts a JSON array of filter condition objects:
 ```
 
 <Warning>
-`field` **must be a typed path** (prefixed by its category — see the table
+`field` **must be a typed path** (prefixed by its category; see the table
 below). The CLI rejects a bare/untyped field (e.g. `net_worth_usd`) with an
-error, because the API would otherwise **silently ignore** it — no error, no
+error, because the API would otherwise **silently ignore** it: no error, no
 filtering, returning the entire unfiltered dataset. Always prefix the field,
 e.g. `users.net_worth_usd`.
 </Warning>

cli/profiles.mdx

@@ -166,12 +166,12 @@ This is an **aggregate table**. Most columns require `-Merge` functions. Always
 | `os` | AggregateFunction(argMax, String, DateTime) | `argMaxMerge(os)` |
 | `activity_dates` | AggregateFunction(groupUniqArrayIf, Date, UInt8) | `groupUniqArrayIfMerge(activity_dates)` |
 
-**Lifecycle definitions** (based on `activity_dates`):
-- **New**: `first_seen` within 30 days
-- **Churned**: `last_seen` >= 30 days ago
-- **Power**: 5+ unique active days in last 30 days
-- **Resurrected**: had 30+ day gap but returned
-- **Returning**: default
+**Lifecycle definitions** (based on `activity_dates`, computed against a reference date that defaults to today):
+- **New**: `first_seen` within the last 30 days
+- **Power**: `first_seen` more than 30 days ago and 5+ unique active days in the last 30 days
+- **Resurrected**: `first_seen` more than 30 days ago and re-engaged within the last 30 days after a 30+ day gap
+- **Churned**: `last_seen` more than 30 days ago
+- **Returning**: default (first seen more than 30 days ago, active recently, but not Power or Resurrected)
 
 **Example:**
 

data/catalog.mdx

@@ -254,12 +254,6 @@ CLV estimates the total revenue a user generates over their entire engagement wi
 
 ### User lifecycle
 
-The lifecycle stage of each wallet or visitor, automatically calculated based on their activity patterns. There are five lifecycle stages:
+The lifecycle stage of each wallet or visitor (New, Returning, Power User, Resurrected, or Churned), computed from their activity recency and frequency relative to a reference date.
 
-- **New** - Wallets engaging with your app for the first time.
-- **Returning** - Users who consistently return after their first interaction.
-- **Power Users** - Returning users who very frequently use your app (active on at least 5 days out of the last 30 days).
-- **Churned** - Wallets that stopped engaging after being active (e.g., 30 days of inactivity).
-- **Resurrected** - Wallets that were once inactive but have re-engaged.
-
-See [User Lifecycle](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for full details on how each stage is determined.
+See [User Lifecycle](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for the exact rules and thresholds for each stage.

data/metrics.mdx

@@ -37,7 +37,7 @@ Get real-time notifications when high-value users interact with your app. This g
 | Setting | Description |
 |---------|-------------|
 | **Name** | Descriptive name (e.g., "Whale Alert") |
-| **Trigger Type** | Event alerts (User alerts coming soon — see below) |
+| **Trigger Type** | Event alerts (User alerts coming soon; see below) |
 | **Conditions** | Filter conditions (optional) |
 | **Notification** | Webhook (generic HTTP or Slack via an incoming-webhook URL) |
 
@@ -59,7 +59,7 @@ Currently, **Event alerts** are the supported, working trigger type. **User aler
     You can add conditions to filter on event properties (e.g., `chain_id = 8453`, `status = failed`).
   </Tab>
   <Tab title="Users (coming soon)">
-    <Note>User alerts are not yet available — the User trigger type is disabled in the dashboard. The behavior below describes the planned functionality.</Note>
+    <Note>User alerts are not yet available; the User trigger type is disabled in the dashboard. The behavior below describes the planned functionality.</Note>
 
     Triggers when a user profile matches your filters. Formo checks for matching users every 5 minutes and sends a notification for each new user that meets your criteria.
 
@@ -319,7 +319,7 @@ Each message includes:
 
 ### User alerts (coming soon)
 
-<Note>User alerts are not yet available — the User trigger type is disabled in the dashboard. The payload format below documents the planned behavior.</Note>
+<Note>User alerts are not yet available; the User trigger type is disabled in the dashboard. The payload format below documents the planned behavior.</Note>
 
 When a user alert is triggered, Formo sends matching user profiles to your webhook.
 

features/product-analytics/alerts.mdx

@@ -62,15 +62,15 @@ Click on any wallet address to open its full profile. The wallet profile shows:
 
 Formo automatically categorizes users by lifecycle stage based on their activity:
 
-| Stage | Definition | What it means |
-|-------|------------|---------------|
-| **New** | First interaction with your app | Recent acquisition |
-| **Returning** | Came back after first visit | Engaged user |
-| **Power User** | Active 5+ days in last 30 days | Highly engaged |
-| **Churned** | No activity for 30+ days | Needs re-engagement |
-| **Resurrected** | Returned after being churned | Re-engaged user |
+| Stage | What it means |
+|-------|---------------|
+| **New** | Recent acquisition |
+| **Returning** | Engaged user |
+| **Power User** | Highly engaged |
+| **Resurrected** | Re-engaged after going quiet |
+| **Churned** | Needs re-engagement |
 
-Use the lifecycle filter on the Users page to focus on specific user groups.
+Use the lifecycle filter on the Users page to focus on specific user groups. See [User Lifecycle](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for the exact rules and thresholds behind each stage.
 
 ### Step 4: Create your first segment
 
@@ -110,7 +110,7 @@ Export this segment as CSV to run targeted re-engagement campaigns on social cha
     Formo aggregates onchain data across all major EVM chains to build wallet profiles. This includes token holdings, DeFi positions, wallet age, transaction frequency, and net worth. Data is refreshed periodically to keep profiles current.
   </Accordion>
   <Accordion title="How are wallet lifecycle stages calculated?">
-    Wallet lifecycle stages (New, Returning, Power User, Churned, Resurrected) are calculated based on activity recency and frequency on your app. A wallet with no activity for 30+ days is classified as "Churned," while a wallet active 5+ days in the last 30 days is a "Power User." See [wallet profiles](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for details.
+    Wallet lifecycle stages (New, Returning, Power User, Resurrected, Churned) are calculated based on activity recency and frequency on your app, relative to a reference date that defaults to today. For example, a wallet last seen more than 30 days ago is classified as "Churned," while a wallet first seen 30+ days ago and active on 5+ of the last 30 days is a "Power User." Default thresholds can be customized in Settings → Lifecycle. See [wallet profiles](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for details.
   </Accordion>
   <Accordion title="Can I export wallet profiles and segments for marketing campaigns?">
     Yes. You can export any [segment](/features/wallet-intelligence/segments) as a CSV file for use in targeted re-engagement campaigns. You can also query profiles programmatically via the [Profiles API](/api/profiles/get).

features/wallet-intelligence/overview.mdx

@@ -22,15 +22,15 @@ Gain a complete view of each user's behaviour across chains and platforms:
 
 ## User Lifecycle
 
-Each user's lifecycle stage is automatically calculated based on their activity:
+Each user's lifecycle stage is computed relative to a **reference date** (the end of the queried date range, which defaults to today). The default thresholds are shown below; projects can override them in **Settings → Lifecycle**.
 
-| Lifecycle | Description |
+| Lifecycle | Definition |
 |:----------|:------------|
-| **New** | Wallets engaging with your app for the first time. A spike in new wallets indicates a successful campaign or marketing push. |
-| **Returning** | Users who consistently return after their first interaction. Low retention may indicate issues with user experience or platform value. |
-| **Power Users** | Returning users who very frequently use your app (active on at least 5 days out of the last 30 days). |
-| **Churned** | Wallets that stopped engaging after being active (e.g., 30 days of inactivity). An increase signals a need to reassess engagement strategies. |
-| **Resurrected** | Wallets that were once inactive but have re-engaged. Useful for evaluating re-engagement campaigns. |
+| **New** | First seen within the last 30 days. |
+| **Returning** | First seen more than 30 days ago, active within the last 30 days, but on fewer than 5 distinct days and with no 30+ day inactivity gap in their history. |
+| **Power Users** | First seen more than 30 days ago and active on at least 5 of the last 30 days. |
+| **Resurrected** | Re-engaged within the last 30 days after a 30+ day inactivity gap. |
+| **Churned** | Last seen more than 30 days ago. |
 
 Filter users by lifecycle to create [segments](/features/wallet-intelligence/segments) and audiences. For example, "Show me whales who use app X who are power users" or "Show me high net worth wallets who have churned."
 
@@ -183,12 +183,12 @@ Each event shows:
 
 The **Apps** and **Tokens** tabs show the user's onchain footprint:
 
-**Apps tab — DeFi positions:**
+**Apps tab (DeFi positions):**
 - Active positions in protocols (Aave, Uniswap, etc.) across supported chains
 - USD value and portfolio percentage for each position
 - Useful for understanding which crypto apps the wallet interacts with
 
-**Tokens tab — token balances:**
+**Tokens tab (token balances):**
 - All tokens held across supported chains
 - Token amounts, USD values, and portfolio percentages
 

features/wallet-intelligence/wallet-profiles.mdx

@@ -147,13 +147,7 @@ Not all active users are equal. Segment by behavior and value.
 
 Formo automatically categorizes users by lifecycle:
 
-| Segment | Definition |
-|---------|------------|
-| **New** | First activity in last 30 days |
-| **Returning** | Multiple sessions, active recently |
-| **Power User** | Active 5+ days in last 30 days |
-| **Churned** | No activity for 30+ days |
-| **Resurrected** | Returned after being churned |
+Formo classifies every wallet into one lifecycle stage (**New**, **Returning**, **Power User**, **Resurrected**, or **Churned**) based on activity recency and frequency. See [User Lifecycle](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for the exact rules and thresholds.
 
 View these segments by going to **Users** and applying the **Lifecycle** filter.