docs(indexing): add tier ux hint and expand README

Author: jruokola

README.md

@@ -52,6 +52,11 @@ Indexing is tiered so you can choose between speed/storage and graph richness. T
 | `balanced` | LSP symbols + docs/enrichment + module linking | Good agentic results without full cost |
 | `full` | All analyzers + LSP definitions + dataflow + architecture | Maximum accuracy/richness |
 
+Tier behavior details:
+- `fast`: disables build context, LSP, enrichment, module linking, dataflow, docs/contracts, and architecture; filters out `Uses`/`References` edges.
+- `balanced`: enables build context, LSP symbols, enrichment, module linking, and docs/contracts; filters out `References` edges.
+- `full`: enables all analyzers and LSP definitions; no edge filtering.
+
 Configure the tier:
 - CLI: `codegraph index --index-tier balanced`
 - Env: `CODEGRAPH_INDEX_TIER=balanced`

crates/codegraph-mcp-server/src/bin/codegraph.rs

@@ -1131,9 +1131,25 @@ async fn handle_index(
         ))?;
     }
 
+    let tier = index_tier.map(Into::into).unwrap_or(config.indexing.tier);
+    let tier_hint = match tier {
+        codegraph_core::config_manager::IndexingTier::Fast => {
+            "fast (speed-first: AST + core edges)"
+        }
+        codegraph_core::config_manager::IndexingTier::Balanced => {
+            "balanced (adds LSP symbols + enrichment)"
+        }
+        codegraph_core::config_manager::IndexingTier::Full => {
+            "full (max detail: LSP definitions + dataflow + architecture)"
+        }
+    };
+    multi_progress.println(format!(
+        "🧭 Indexing tier: {} — override with --index-tier or CODEGRAPH_INDEX_TIER",
+        tier_hint
+    ))?;
+
     // Configure indexer
     let languages_list = languages.clone().unwrap_or_default();
-    let tier = index_tier.map(Into::into).unwrap_or(config.indexing.tier);
     let indexer_config = IndexerConfig {
         languages: languages_list.clone(),
         exclude_patterns: exclude,