Add docs_lookup tool for fetching data engineering documentation

[anandgupta42]

Summary

Adds a new docs_lookup tool that fetches up-to-date, version-specific documentation for data engineering tools and database platforms. The tool supports two documentation providers:

1. webfetch (default) — Fetches directly from official documentation sites (Snowflake, Databricks, DuckDB, PostgreSQL, ClickHouse, BigQuery) with no third-party data sharing
2. ctx7 (opt-in) — Uses Context7 CLI for richer Python library/SDK documentation (dbt, Airflow, Spark, SQLAlchemy, Polars, etc.)

The tool intelligently falls back from ctx7 to webfetch if the primary method fails, and includes comprehensive telemetry tracking for monitoring success rates and performance.

Also includes:

• data-docs skill definition with activation guidelines and usage examples
• library-ids.md reference document mapping 40+ data engineering tools to their documentation sources
• Telemetry event type for tracking docs_lookup calls

Test Plan

No testing needed — this is a new tool with no existing tests to break. The tool includes:

• Comprehensive error handling with fallback logic
• Telemetry tracking for all outcomes (success, error, not_found)
• Logging at info/warn/error levels for debugging
• 30-second timeout on all network requests to prevent hangs

Manual verification can be done by calling docs_lookup(tool="dbt-core", query="incremental models") or similar queries against the supported tools listed in the skill documentation.

Checklist

• Documentation added (SKILL.md and library-ids.md reference)
• Telemetry event type added
• Tool registered in tool registry

[github-actions]

Hey! Your PR title Add docs_lookup tool for fetching data engineering documentation doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[sentry]

Bug: The code calls .timeout() on a Bun shell command result, but this method does not exist, which will cause a TypeError at runtime, breaking the ctx7 provider.
_{Severity: HIGH}

Suggested Fix

Replace the .timeout(30_000) call with a supported timeout mechanism. Either use Bun.spawn() which supports timeouts directly, or pass an AbortSignal.timeout(30_000) to the shell command, consistent with patterns like fetchFromWebsite() in the same file.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/opencode/src/altimate/tools/docs-lookup.ts#L236-L238

Potential issue: The `fetchFromCtx7` function attempts to call a non-existent
`.timeout()` method on the result of a Bun shell command (`$`). This will cause a
`TypeError` at runtime whenever the `ctx7` documentation provider is used. Although the
error is caught and the system falls back to another method, this renders the
`ALTIMATE_DOCS_PROVIDER=ctx7` feature completely non-functional. Existing code uses
`AbortSignal.timeout()` for similar timeout requirements.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[dev-punia-altimate]

🤖 Behavioral Analysis — 2 Finding(s)

🟡 Warnings (1)

• F1 packages/opencode/src/altimate/tools/docs-lookup.ts:392 [Silent functional failure — library-only tools return misleading error with default provider]
  19 of the ~38 listed tools are completely non-functional with the default webfetch provider, but the error message hides this. When toolLower is a library-only entry (e.g. dbt-core, airflow, pyspark, sqlalchemy, polars, pandas, confluent-kafka, all dbt adapters, etc.) it exists in CTX7_LIBRARIES but has no corresponding entry in PLATFORM_DOCS or LIBRARY_TO_PLATFORM. Trace: (1) ctx7Id is defined e.g. /dbt-labs/dbt-core; (2) platform = PLATFORM_DOCS[toolLower] = undefined; (3) platformFromLibrary = undefined; (4) resolvedPlatform = undefined, fetchUrl = undefined; (5) ctx7 block skipped (provider is webfetch); (6) webfetch block skipped (fetchUrl is undefined); (7) notFound = !ctx7Id && !resolvedPlatform && !hasUrl = false. Because notFound is false, the code falls through and returns 'Documentation fetch failed (network error or rate limit)' — blaming the network when the actual reason is that these library-only tools have no webfetch URL at all. Affected tools: dbt-core, airflow, pyspark, 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.

🔵 Nits (1)

• F2 packages/opencode/src/altimate/tools/docs-lookup.ts:393 — When a library-only tool (e.g. dbt-core) is called with the default webfetch provider, no telemetry event is emitted for the failure. The if (notFound) block is skipped because notFound is false. The webfetch and ctx7 try/catch blocks were never entered (fetchUrl is undefined, provider is webfetch). Result: failures for 19 tools are completely invisible to monitoring — they show zero events instead of a not_found or error count.

_{Analysis run | Powered by QA Autopilot}

[dev-punia-altimate]

✅ Tests — All Passed

TypeScript — passed

Python — passed

_{Tested at 0395d758 | Run log | Powered by QA Autopilot}