feat: add docs_lookup tool with telemetry and failure logging

Create a dedicated docs_lookup tool that wraps Context7 CLI and web
fetch with full telemetry integration. Tracks every documentation
lookup (tool_id, method, status, duration, errors) via the existing
Azure Application Insights pipeline.

Changes:
- New docs_lookup tool (src/altimate/tools/docs-lookup.ts)
  - Tries ctx7 first for library docs, falls back to webfetch for
    platform docs
  - Logs success, not_found, and error statuses with duration
  - Surfaces unknown tools and network failures clearly
- New telemetry event type: docs_lookup
  - Tracks: tool_id, method (ctx7/webfetch), status, duration_ms,
    error message, source_url
  - Added "docs" category to tool categorization
- Registered in tool registry alongside other altimate tools
- Updated data-docs skill to use docs_lookup tool instead of raw
  bash/webfetch calls

https://claude.ai/code/session_01NZPdvEHNXDcmhgJt9RLMu1

Author: claude

.opencode/skills/data-docs/SKILL.md

@@ -15,6 +15,9 @@ When writing code or answering questions about data engineering tools,
 use this skill to fetch current, version-specific documentation instead
 of relying on training data.
 
+## Requirements
+**Tools used:** docs_lookup, glob, read
+
 ## When to Use
 
 Activate this skill when the user:
@@ -35,108 +38,83 @@ Activate this skill when the user:
 - Asks "how do I" questions about any data engineering library or platform
 - Needs SQL syntax, API references, method signatures, or configuration options
 
-## Documentation Sources
-
-This skill uses **two methods** depending on the type of documentation:
-
-1. **Context7 CLI** (`ctx7`) — For Python libraries and SDKs (dbt-core, Airflow,
-   PySpark, Snowpark, etc.). These have indexed documentation in Context7.
-2. **Web Fetch** (`webfetch`) — For database platform SQL documentation (Snowflake SQL,
-   BigQuery SQL, Databricks SQL, DuckDB, PostgreSQL, ClickHouse). These platforms
-   maintain official docs sites that can be fetched directly.
-
-Check `references/library-ids.md` for the full mapping of which method to use.
-
-## Method 1: Context7 CLI (for Python libraries/SDKs)
+## How to Fetch Documentation
 
-### Step 1: Identify the Library
-
-Check the `references/library-ids.md` file for pre-mapped Context7 library IDs.
-If you find a match, skip to Step 3.
-
-If the library isn't in the reference file, resolve it:
-
-```bash
-npx -y ctx7@latest library <library-name> "<user's question>"
-```
+### Step 1: Identify the Tool
 
-Pick the result with the closest name match and highest score.
-Note the Library ID (format: `/org/project` or `/org/project/version`).
+Determine which data engineering tool or platform the user is asking about.
+Check `references/library-ids.md` for the full list of supported tools.
 
-### Step 2: Check for Project Version
+### Step 2: Check for Project Version (optional)
 
 Look for version info in the user's project:
 
 - `requirements.txt` or `pyproject.toml` — Python package versions
 - `dbt_project.yml` — dbt version (`require-dbt-version`)
 - `packages.yml` — dbt package versions
-- `setup.py` or `setup.cfg` — Python package versions
 
-If a specific version is found, prefer version-specific library IDs
-(format: `/org/project/vX.Y.Z`) when available from the resolution step.
+### Step 3: Use the `docs_lookup` Tool
 
-### Step 3: Query Documentation
+Call the `docs_lookup` tool with the tool name and a specific query:
 
-```bash
-npx -y ctx7@latest docs <libraryId> "<specific question>"
+```
+docs_lookup(tool="dbt-core", query="how to create incremental models with merge strategy")
+docs_lookup(tool="snowflake", query="MERGE statement syntax and examples")
+docs_lookup(tool="duckdb", query="window functions syntax")
+docs_lookup(tool="postgresql", query="JSONB operators and functions")
+docs_lookup(tool="clickhouse", query="MergeTree engine settings")
 ```
 
-Write **specific, detailed queries** for better results:
-- Good: `"How to create incremental models with merge strategy in dbt"`
-- Bad: `"incremental"`
-
-## Method 2: Web Fetch (for database platform SQL docs)
-
-For Snowflake, BigQuery, Databricks, DuckDB, PostgreSQL, and ClickHouse
-platform documentation (SQL syntax, functions, DDL, configuration), use
-the `webfetch` tool to fetch specific documentation pages.
-
-### Step 1: Find the Right URL
-
-Check `references/library-ids.md` for the **Platform Documentation URLs**
-section. Each platform has a base URL and common page paths listed.
-
-### Step 2: Fetch the Documentation
+The tool automatically selects the best method:
+- **Context7 (ctx7)** for Python libraries/SDKs — indexed, searchable docs
+- **Web fetch** for database platforms — fetches from official documentation sites
 
-Use the `webfetch` tool with the specific documentation URL and a prompt
-describing what information to extract:
+For platform docs with a **specific page URL** (see `references/library-ids.md`),
+pass it via the `url` parameter for better results:
 
 ```
-webfetch(url="https://docs.snowflake.com/en/sql-reference/sql/merge",
-         prompt="Extract the full MERGE syntax, parameters, and examples")
+docs_lookup(tool="snowflake", query="MERGE syntax", url="https://docs.snowflake.com/en/sql-reference/sql/merge")
+docs_lookup(tool="postgresql", query="JSON functions", url="https://www.postgresql.org/docs/current/functions-json.html")
 ```
 
-### Step 3: Use the Documentation
+### Step 4: Use the Documentation
 
 - Answer using the fetched documentation, not training data
 - Include relevant code examples from the docs
-- Cite the documentation URL for reference
+- Cite the library version or documentation URL when relevant
 - If docs mention deprecations or breaking changes, highlight them
 
+## Supported Tools
+
+**Libraries/SDKs (via Context7):** dbt-core, airflow, pyspark, snowflake-connector-python,
+snowpark-python, google-cloud-bigquery, databricks-sdk, duckdb, psycopg2, psycopg,
+clickhouse-connect, confluent-kafka, sqlalchemy, polars, pandas, great-expectations,
+dbt-utils, dbt-expectations, dbt-snowflake, dbt-bigquery, dbt-databricks, dbt-postgres,
+dbt-redshift, dbt-spark, dbt-duckdb, dbt-clickhouse, elementary
+
+**Platforms (via web fetch):** snowflake, databricks, duckdb, postgresql, clickhouse, bigquery
+
 ## Guidelines
 
-- Maximum 3 CLI/webfetch calls per user question to avoid rate limits
-- Context7 works without authentication; set `CONTEXT7_API_KEY` for higher limits
-- If a call fails (network error, rate limit), fall back to training data
-  and note that the docs could not be fetched
+- Maximum 3 `docs_lookup` calls per user question to avoid rate limits
+- If a call fails, the tool logs the failure automatically for improvement tracking
+- On failure, fall back to training data and note that docs could not be fetched
 - For dbt: always check `dbt_project.yml` for version and `packages.yml` for packages
 - For Python tools: check `requirements.txt` or `pyproject.toml` for pinned versions
 - When multiple libraries are relevant (e.g., dbt-core + dbt-snowflake), fetch docs
   for the most specific one first
-- For SQL platform docs, prefer the most specific page URL (e.g., the MERGE
-  statement page, not the general SQL reference index)
+- For SQL platform docs, pass a specific page URL via the `url` parameter for best results
 
 ## Usage
 
 - `/data-docs How do I create an incremental model in dbt?`
 - `/data-docs What Airflow operators are available for BigQuery?`
 - `/data-docs How to use window functions in PySpark?`
-- `/data-docs Snowpark DataFrame API for joins`
 - `/data-docs Snowflake MERGE statement syntax`
 - `/data-docs DuckDB window functions`
 - `/data-docs PostgreSQL JSONB operators`
 - `/data-docs ClickHouse MergeTree engine settings`
 
-Use the bash tool to run `ctx7` CLI commands for libraries, and the `webfetch`
-tool for platform SQL documentation. Reference `library-ids.md` for the full
-mapping of tools, IDs, and URLs.
+Use the `docs_lookup` tool for all documentation lookups. It handles method selection,
+telemetry, and failure logging automatically. Reference `library-ids.md` for the full
+mapping of tools, IDs, and documentation URLs.

packages/opencode/src/altimate/telemetry/index.ts

@@ -274,6 +274,17 @@ export namespace Telemetry {
         budget: number
         scopes_used: string[]
       }
+    | {
+        type: "docs_lookup"
+        timestamp: number
+        session_id: string
+        tool_id: string
+        method: "ctx7" | "webfetch"
+        status: "success" | "error" | "not_found"
+        duration_ms: number
+        error?: string
+        source_url?: string
+      }
 
   const FILE_TOOLS = new Set(["read", "write", "edit", "glob", "grep", "bash"])
 
@@ -287,6 +298,7 @@ export namespace Telemetry {
     { category: "warehouse", keywords: ["warehouse", "connection"] },
     { category: "lineage", keywords: ["lineage", "dag"] },
     { category: "memory", keywords: ["memory"] },
+    { category: "docs", keywords: ["docs_lookup"] },
   ]
 
   export function categorizeToolName(name: string, type: "standard" | "mcp"): string {