docs: fix staleness vs latest ../formono and tighten guides (#86)

* docs: fix staleness vs latest ../formono and tighten guides

Audited the docs against the current backend, SDKs, frontend, and the
published @formo/cli, and corrected stale or incorrect content.

HIGH
- wallet-labels: replace the old session-count lifecycle table with a
  link to the canonical 6-stage definition; drop invented labels
  (DeFi Active, ETH Staker) in favor of real filters (Apps, Lifecycle).
- integrations: only webhook alerts ship (Slack via webhook URL); drop
  the unimplemented Email channel.
- metrics: channel #5 is "Referrals" (code value), not "Affiliates".

MED
- chains: BOB and BOB Testnet are indexed for contract events.
- mcp: document the project_users tool; fix the "not a tool" note and
  the lifecycle tool description.
- cli: output defaults to TOON (not raw JSON); document the incur
  output flags; jq examples need --json; query desc had wrong formats.
- charts: add Stacked Bar and Area chart types.
- guides: chart button is "Add Chart"; chart type is "Funnel"/"Flow"
  not "Conversion Funnel"/"User Path"; nav is "Explorer"; fix typos.
- events: points is a Number (not String).
- security: bump SRI example to analytics@1.33.0 with the hash from the
  GitHub release; remove the non-existent "Delete forms" role permission.

LOW
- metrics: complete AI-assistant domains; widen Email/Organic Social
  rules; channels are assigned at ingestion, not query time.
- sql-explorer: reframe the session-count bucket query so it no longer
  masquerades as the lifecycle definition.

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

* docs: fix broken example link (next-app-router -> with-next-app-router)

The getformo/examples repo folder is named with-next-app-router; the
bare next-app-router path 404s.

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

---------

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

Author: yosriady

chains/overview.mdx

@@ -36,8 +36,8 @@ Formo supports builders on Ethereum and all major EVM chains.
 | Bitlayer                  | ✅    | ✅        | ✖️        | ✖️        |
 | Blast Mainnet             | ✅    | ✅        | ✅        | ✅        |
 | Blast Sepolia             | ✅    | ✖️        | ✖️        | ✅        |
-| BOB                       | ✅    | ✅        | ✖️        | ✅        |
-| BOB Testnet               | ✅    | ✖️        | ✖️        | ✅        |
+| BOB                       | ✅    | ✅        | ✅        | ✅        |
+| BOB Testnet               | ✅    | ✖️        | ✅        | ✅        |
 | BNB Smart Chain Mainnet   | ✅    | ✅        | ✅        | ✅        |
 | BNB Smart Chain Testnet   | ✅    | ✖️        | ✅        | ✅        |
 | Boba                      | ✅    | ✅        | ✖️        | ✖️        |

cli/analytics.mdx

@@ -94,7 +94,7 @@ formo analytics revenue_timeseries \
   --params '{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'
 
 # Pipe results to jq for processing
-formo analytics kpis | jq '.data'
+formo analytics kpis --json | jq '.data'
 ```
 
 The response shape matches the dashboard data: `{ meta, data, rows, statistics }`.

cli/overview.mdx

@@ -149,15 +149,23 @@ The CLI stores configuration at `~/.config/formo/config.json` with restricted pe
 
 ## Output format
 
-- **Interactive mode (TTY):** The CLI displays colored, human-readable output with status icons and formatting.
-- **Piped/scripted mode:** The CLI outputs raw JSON, making it easy to pipe into `jq` or other tools.
+By default, commands print compact, human-readable TOON output. Pass one of the standard output flags to change the format:
+
+| Flag | Description |
+|------|-------------|
+| `--format <toon\|json\|yaml\|md\|jsonl>` | Output format (default: `toon`) |
+| `--json` | Shorthand for `--format json` |
+| `--verbose` | Include the full response envelope (`ok`, `data`, `meta`) |
+| `--filter-output <keys>` | Filter output by key paths (e.g. `data,meta.duration`) |
+
+Status messages (login confirmation, errors, and similar) are written to stderr in interactive terminals, so they never pollute piped output.
 
 ```bash
-# Human-friendly output
+# Default TOON output
 formo profiles get vitalik.eth
 
-# Pipe JSON to jq
-formo profiles get vitalik.eth | jq '.net_worth_usd'
+# JSON output, piped to jq
+formo profiles get vitalik.eth --json | jq '.net_worth_usd'
 ```
 
 ## AI agent usage

cli/query.mdx

@@ -2,7 +2,7 @@
 title: "Query"
 sidebarTitle: "Query"
 icon: database
-description: "Run ClickHouse SQL queries against your Formo analytics data warehouse directly from the terminal and output results in table, JSON, or CSV format."
+description: "Run ClickHouse SQL queries against your Formo analytics data warehouse directly from the terminal, with results in TOON, JSON, or other output formats."
 ---
 
 The `formo query run` command lets you execute SQL queries against your Formo analytics data warehouse directly from the terminal.
@@ -34,12 +34,12 @@ formo query run "SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net
 formo query run "SELECT DATE(timestamp) as day, COUNT(DISTINCT address) as dau FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY day ORDER BY day"
 
 # Pipe results to jq for processing
-formo query run "SELECT count(*) as total FROM events" | jq '.data'
+formo query run "SELECT count(*) as total FROM events" --json | jq '.data'
 ```
 
 ### Tips
 
 - SQL queries execute against your project's analytics data warehouse.
 - Wrap your query in double quotes to prevent shell interpretation.
 - Use single quotes inside your SQL for string literals.
-- Pipe the output to `jq` for JSON processing in scripts.
+- Pass `--json` and pipe the output to `jq` for processing in scripts (default output is TOON).

data/events/track.mdx

@@ -50,7 +50,7 @@ Include these optional properties in a custom event to track values associated w
 | `volume` | Number | The volume amount as a result of an event. For e.g., a token swap worth $20.00 would result in a volume of 20.00. Can be positive or negative e.g. send -100 to track outflows. |
 | `revenue` | Number | The revenue amount as a result of an event. For e.g., a transaction with a protocol fee of $5.00 would result in a revenue of 5.00. Must be a non-negative number.|
 | `currency` | String | The currency of the revenue as a result of the event, set in ISO 4217 format. If this is not set, Formo assumes the revenue is in USD. |
-| `points` | String | An abstract value such as points or XP associated with an event, to be used by various teams. |
+| `points` | Number | An abstract value such as points or XP associated with an event, to be used by various teams. |
 
 <Frame caption="Revenue tracking.">
 	<img src="/images/revenue.png" alt="Revenue tracking." />
@@ -63,10 +63,10 @@ Include these optional properties in a custom event to track values associated w
   "type": "track",
   "event": "Product Reviewed",
   "properties": {
-    "volume": "-100.5",
-    "revenue": "20.5",
+    "volume": -100.5,
+    "revenue": 20.5,
     "currency": "USD",
-    "points": "100",
+    "points": 100,
     "product_id" : "9578257311",
     "rating" : 3.0,
     "review_body" : "Good value for the price."

data/metrics.mdx

@@ -86,19 +86,19 @@ To minimize the amount of traffic that falls within the "Direct / None" category
 
 ### Channel
 
-The acquisition channel that brought a session to your app. Every session is assigned to exactly one of 12 channels at query time, using a priority-ordered ladder over referrer domain, `utm_medium`, and 8 ad-platform click IDs (`gclid`, `gad_source`, `fbclid`, `msclkid`, `ttclid`, `twclid`, `li_fat_id`, `rdt_cid`).
+The acquisition channel that brought a session to your app. Every session is assigned to exactly one of 12 channels when its events are ingested, using a priority-ordered ladder over referrer domain, `utm_source`, `utm_medium`, and 8 ad-platform click IDs (`gclid`, `gad_source`, `fbclid`, `msclkid`, `ttclid`, `twclid`, `li_fat_id`, `rdt_cid`). The channel is stored on the event, so queries read it back without recomputing.
 
 | # | Channel | Definition |
 |---|---------|------------|
 | 1 | Paid Search | Paid signal + referrer is a search engine (Google, Bing, DuckDuckGo, Yahoo, Yandex, Baidu, Brave, Kagi, Naver, ...) |
 | 2 | Paid Video | Paid signal + referrer is a video platform (YouTube, Vimeo, Twitch, Dailymotion, Loom, Wistia) |
 | 3 | Paid Social | Paid signal + referrer is a social platform (Meta, X, LinkedIn, Reddit, TikTok, Pinterest, Snapchat, Threads, Discord, Telegram, Farcaster, ...) |
-| 4 | Email | `utm_medium` ∈ \{`email`, `e-mail`, `e_mail`, `newsletter`\} |
-| 5 | Affiliates | `utm_medium=affiliate` or non-empty `ref` query parameter |
+| 4 | Email | `utm_medium` ∈ \{`email`, `e-mail`, `e_mail`, `newsletter`\}, or referrer is a known email or newsletter domain (Gmail, Proton Mail, Yahoo Mail, Outlook, Substack, Beehiiv, Paragraph) |
+| 5 | Referrals | `utm_medium=affiliate` or non-empty `ref` query parameter |
 | 6 | Display | `utm_medium` ∈ \{`display`, `banner`, `expandable`, `interstitial`\} |
-| 7 | AI | Referrer is an AI assistant domain (ChatGPT, Claude, Gemini, Copilot, Perplexity, DeepSeek, Phind, Poe, Mistral Chat, Meta AI, You.com, Pi) |
+| 7 | AI | Referrer is an AI assistant domain (ChatGPT, Claude, Gemini, Copilot, Perplexity, DeepSeek, Phind, Poe, Mistral Chat, Meta AI, You.com, Pi, Grok, Qwen, Kimi, Hugging Face, Genspark) |
 | 8 | Organic Search | `utm_medium=organic` or referrer is a search engine with no paid signal |
-| 9 | Organic Social | `utm_medium` ∈ \{`social`, `social-network`, `social-media`, `sm`\} or referrer is a social platform with no paid signal |
+| 9 | Organic Social | `utm_medium` ∈ \{`social`, `social-network`, `social-media`, `sm`, `social network`, `social media`\} or referrer is a social platform with no paid signal |
 | 10 | Organic Video | Referrer is a video platform with no paid signal |
 | 11 | Referrers | Any other non-empty referrer not matched by the rules above |
 | 12 | Direct | No referrer, no UTM, no click ID (typed URL, bookmark, or stripped referrer) |

features/product-analytics/charts.mdx

@@ -66,7 +66,9 @@ Here is the current list of supported chart types on Formo:
 - Table
 - Number
 - Bar
+- Stacked Bar
 - Line
+- Area
 - Pie
 
 Add beautiful, interactive visualizations that make your data easy to understand.
@@ -149,7 +151,9 @@ After running your query, select the chart type that best represents your data:
 | Chart Type | Best for |
 |------------|----------|
 | **Line** | Trends over time |
+| **Area** | Cumulative trends over time |
 | **Bar** | Comparing categories |
+| **Stacked Bar** | Comparing categories across segments |
 | **Pie** | Showing proportions |
 | **Number** | Single KPI metric |
 | **Table** | Detailed data exploration |

features/wallet-intelligence/wallet-labels.mdx

@@ -17,11 +17,7 @@ Each tracked user on Formo is assigned labels based on their onchain activity an
 
 ### User lifecycle labels
 
-| Label | Description |
-|-------|-------------|
-| **New User** | Number of sessions = 1 |
-| **Returning User** | Number of sessions > 1 and < 10 |
-| **Power User** | Number of sessions > 10 |
+Every wallet is assigned a lifecycle stage based on its recency and active days: **New**, **Returning**, **Power User**, **Resurrected**, **At Risk**, or **Churned**. See [User lifecycle](/features/wallet-intelligence/wallet-profiles#user-lifecycle) for the exact rules and thresholds.
 
 ### Attestations
 
@@ -53,9 +49,10 @@ Wallet labels turn anonymous addresses into actionable user profiles. This guide
 Formo automatically analyzes each wallet's onchain activity and assigns relevant labels. Labels update as users' behavior changes.
 
 **Label sources:**
-- **Onchain activity** - Protocols used, tokens held, transaction patterns
-- **Attestations** - Verified credentials from Coinbase, Gitcoin Passport, etc.
-- **App behavior** - Session count, engagement patterns on your app
+- **Lifecycle** - Engagement stage derived from each wallet's recency and active days
+- **Attestations** - Verified credentials from Coinbase, Binance, Human Passport, and OFAC sanction lists
+- **Campaigns** - Participation in incentive campaigns such as Merkl
+- **Onchain registries** - Standards such as ERC-8004 that identify AI agent wallets
 
 ### Step 1: View labels on a user profile
 
@@ -78,7 +75,7 @@ Use labels to find specific user types:
 
 | Goal | Label Filter |
 |------|--------------|
-| Find DeFi power users | Label = "DeFi Active" AND Label = "Power User" |
+| Find power users | Lifecycle = "Power User" |
 | Find verified humans | Human Passport Score > 50 |
 | Exclude sanctioned wallets | Label != "Sanctioned User" |
 | Find Coinbase users | Label = "Coinbase Verified Account" |
@@ -90,7 +87,7 @@ Labels become powerful when combined with other criteria:
 **High-value DeFi users:**
 | Filter | Value |
 |--------|-------|
-| Label | DeFi Active |
+| Apps | Uniswap, Aave (or other DeFi protocols) |
 | Net Worth | > $50,000 |
 | Lifecycle | Power User |
 
@@ -104,9 +101,8 @@ Labels become powerful when combined with other criteria:
 **At-risk whales:**
 | Filter | Value |
 |--------|-------|
-| Label | ETH Staker |
 | Net Worth | > $100,000 |
-| Lifecycle | Churned |
+| Lifecycle | At Risk |
 
 ### Step 4: Save as a segment
 
@@ -131,7 +127,7 @@ Turn useful label combinations into reusable segments:
 3. Export clean lists for marketing or rewards
 
 **Quality scoring:**
-1. Combine multiple positive labels (DeFi Active + Power User + Coinbase Verified)
+1. Combine multiple positive labels (Power User + Coinbase Verified Account + Human Passport Score > 50)
 2. Users matching more labels = higher quality
 3. Prioritize multi-label users for outreach
 
@@ -146,8 +142,8 @@ Set up alerts based on labels:
 
 1. Go to **Settings** > **Alerts**
 2. Create an alert for `connect` events
-3. Add condition: Label = "DeFi Active" AND Net Worth > $100,000
-4. Get notified when high-value DeFi users connect
+3. Add condition: Lifecycle = "Power User" AND Net Worth > $100,000
+4. Get notified when high-value power users connect
 
 ### Next Steps
 

guides/contract-events.mdx

@@ -78,13 +78,13 @@ Each contract event is automatically linked to a wallet address and session, so
 
 Now that contract events are flowing, use them as steps in funnels and other charts.
 
-Click **Dashboards** > **Create Chart** > **Conversion Funnel**.
+Click **Dashboards** > **Add Chart** > **Funnel**.
 
 In the funnel builder, you'll see a list of all of your events including events from the frontend (page views, wallet connects) and contract events (swaps, transfers) in the step dropdown.
 
 Example funnel:
 1. "Wallet Connected" (frontend event with type `connect`)
-2. "Transaction" (frontend event with type type `transcation`)
+2. "Transaction" (frontend event with type `transaction`)
 3. "Swap" (contract event: Swap)
 
 This funnel measures: Of users who connected a wallet, how many made a transaction, and of those, how many executed a swap?
@@ -97,7 +97,7 @@ This funnel measures: Of users who connected a wallet, how many made a transacti
 
 For advanced analysis, use the **Explorer** (SQL editor).
 
-Navigate to **Explore** in the sidebar. The schema browser on the left shows available tables: `events`, `users`, `anonymous_users`.
+Navigate to **Explorer** in the sidebar. The schema browser on the left shows available tables: `events`, `users`, `anonymous_users`.
 
 The `events` table includes contract events with columns like:
 - `type`: Event type (e.g., `decoded_log` for contract events, `connect` for wallet connections)

guides/custom-dashboard.mdx

@@ -93,7 +93,7 @@ Click **Share** in the top right to generate a public link. Copy it and share wi
 | **Funnel Chart** | Page view > Connect > Transaction | Where users drop off and your biggest opportunity |
 | **Retention Chart** | D7, D30 cohort retention | Whether users actually come back (stickiness) |
 | **Traffic Sources** | Referrer breakdown | Best acquisition channels to double down on |
-| **User Path (Sankey)** | Common flows | How real users navigate your protocol |
+| **Flow (Sankey)** | Common flows | How real users navigate your protocol |
 
 ## Next Steps