feat: plan agent refinement, feature discovery

docs/docs/configure/warehouses.md

@@ -365,3 +365,16 @@ Testing connection to prod-snowflake (snowflake)...
  Warehouse: COMPUTE_WH
  Database: ANALYTICS
 ```
+
+## Post-Connection Suggestions
+
+After you successfully connect a warehouse, altimate suggests next steps to help you get the most out of your connection. Suggestions are shown progressively based on what you've already done:
+
+1. **Index your schemas** — populate the schema cache for autocomplete and context-aware analysis
+2. **Run SQL analysis** — scan your query history for anti-patterns and optimization opportunities
+3. **Inspect schema structure** — review tables, columns, and relationships
+4. **Check lineage** — trace column-level data flow across your models
+
+If altimate detects a dbt project in your workspace, it also recommends relevant dbt skills (`/dbt-develop`, `/dbt-troubleshoot`, `/dbt-analyze`).
+
+Each suggestion is shown **once per session** — dismissing or acting on a suggestion removes it from the queue. You can also run a suggested action later via its corresponding tool or slash command.

docs/docs/data-engineering/agent-modes.md

@@ -142,6 +142,51 @@ altimate --agent plan
 
 Plan mode restricts the agent to reading files and editing plan files only. No SQL, no bash, no file modifications. Use this to outline an approach before switching to builder to execute it.
 
+### Two-step workflow
+
+Plan mode uses a two-step approach to keep you in control:
+
+1. **Outline** — The agent produces a short outline (3-5 bullet points) summarizing what it intends to do.
+2. **Expand** — After you confirm, the agent expands the outline into a full, detailed plan.
+
+This prevents wasted effort on plans that are heading in the wrong direction.
+
+### Refinement loop
+
+You don't have to start over if the plan isn't quite right. After the agent presents its outline or full plan, you can:
+
+- **Approve** — Accept the plan as-is (e.g., "looks good", "approved", "let's go").
+- **Refine** — Edit specific parts and ask the agent to revise (e.g., "change step 3 to use incremental instead of table").
+- **Reject** — Discard the plan entirely (e.g., "scrap this", "start over", "reject").
+
+Refinements are capped at **5 revisions per session** to avoid endless loops. After the cap is reached, the agent asks you to approve or reject the current version.
+
+### Example conversation
+
+```
+You: Plan a migration of our raw_events table from a view to an incremental model
+
+Plan: Here's my proposed approach:
+ • Inspect the current raw_events view and its downstream dependencies
+ • Design an incremental model with a timestamp-based strategy
+ • Add schema tests for the new model
+ • Create a cutover checklist for swapping the view to the model
+ • Update the dbt DAG documentation
+
+You: Change the second bullet — use insert_overwrite instead of timestamp-based
+
+Plan: Updated outline:
+ • Inspect the current raw_events view and its downstream dependencies
+ • Design an incremental model with an insert_overwrite strategy
+ • Add schema tests for the new model
+ • Create a cutover checklist for swapping the view to the model
+ • Update the dbt DAG documentation
+
+You: Approved
+
+Plan: [expands into a full detailed plan]
+```
+
 ---
 
 ## SQL Write Access Control

docs/docs/getting-started.md

@@ -60,7 +60,7 @@ Set up warehouse connections so altimate can query your data platform. You have
 4. **Offers to configure connections** and walks you through adding and testing each discovered warehouse
 5. **Indexes schemas** to populate the schema cache for autocomplete and context-aware analysis
 
-Once complete, altimate indexes your schemas and detects your tooling, enabling schema-aware autocomplete and context-rich analysis.
+Once complete, altimate indexes your schemas and detects your tooling, enabling schema-aware autocomplete and context-rich analysis. After connecting, you'll see feature suggestions tailored to your warehouse type — such as indexing schemas, running SQL analysis, or checking lineage. These appear progressively and each is shown once per session. See [Post-Connection Suggestions](configure/warehouses.md#post-connection-suggestions) for details.
 
 ### Option B: Manual configuration
 

docs/docs/reference/telemetry.md

@@ -33,7 +33,9 @@ We collect the following categories of events:
 | `error_recovered` | Successful recovery from a transient error (error type, strategy, attempt count) |
 | `mcp_server_census` | MCP server capabilities after connect (tool and resource counts, but no tool names) |
 | `context_overflow_recovered` | Context overflow is handled (strategy) |
-| `skill_used` | A skill is loaded (skill name and source — `builtin`, `global`, or `project` — no skill content) |
+| `skill_used` | A skill is loaded (skill name, source — `builtin`, `global`, or `project`, and trigger — `user`, `auto`, or `suggestion` — no skill content) |
+| `plan_revision` | A plan revision occurs in Plan mode (revision_number, action: `refine`, `approve`, `reject`, or `cap_reached`) |
+| `feature_suggestion` | A post-connection feature suggestion is shown (suggestion_type, suggestions_shown, warehouse_type — no user input) |
 | `sql_execute_failure` | A SQL execution fails (warehouse type, query type, error message, PII-masked SQL — no raw values) |
 | `core_failure` | An internal tool error occurs (tool name, category, error class, truncated error message, PII-safe input signature, and optionally masked arguments — no raw values or credentials) |
 | `first_launch` | Fired once on first CLI run after installation. Contains version and is_upgrade flag. No PII. |

packages/drivers/package.json

@@ -8,6 +8,9 @@
  "./*": "./src/*.ts"
  },
  "files": ["src"],
+ "devDependencies": {
+ "mongodb": "^6.0.0"
+ },
  "optionalDependencies": {
  "pg": "^8.0.0",
  "snowflake-sdk": "^2.0.3",