groundlane: Instructions file for Codex

Groundlane agent instructions

Project boundary

Groundlane is an independent open-source TypeScript project. It is not part of DaoDao and must not import DaoDao-specific code, configuration, terminology, or deployment assumptions.

Architecture

• src/worker/: Cloudflare Worker entry, authentication, routing, and Container lifecycle.
• src/container/: Node.js remote MCP HTTP server running in a Cloudflare Container.
• src/core/: pure orchestration, policies, limits, budgets, and contracts.
• src/adapters/: HTTP, reader, browser, search, and provider integrations.
• src/tools/: MCP tool definitions and handlers.
• test/: unit, contract, integration, and regression tests.
• docs/: product decisions, configuration, deployment, and time-sensitive research.

Keep provider-specific request and response mapping in src/adapters/. Keep routing, quota policy, validation, and shared contracts provider-neutral in src/core/.

Dogfood Groundlane for web access

• Use Groundlane's web_fetch, web_search, and web_extract first for public-web research, documentation checks, and representative smoke tests.
• This rule applies to the primary agent and every subagent.
• When changing Groundlane itself, prefer running the current checkout locally with a temporary development auth token so research exercises the code being edited. Use the deployed MCP only when the task explicitly concerns the deployed version.
• web_fetch and web_extract do not require a third-party search key. web_search must fail closed when no configured search provider is available.
• Follow an explicit user choice of tool or no-fallback requirement. Otherwise, before declaring Groundlane unavailable, inspect the complete callable tool inventory because its MCP tools may be deferred.
• If Groundlane is not mounted or one bounded Groundlane request fails as a whole, choose the best task-matching MCP from the callable inventory. Use the current platform web search/fetch/open tools only when no suitable MCP is callable.
• Keep fallback research evidence separate from Groundlane product evidence. A successful fallback does not prove that the corresponding Groundlane path works or replace a required Groundlane smoke. Briefly disclose the fallback tool and Groundlane failure. Never send secrets, authenticated content, or private data through a fallback service.
• Do not use retired stealth_fetch, WebFetch, web-fetch, fetch_page, or Playwright paths for web retrieval.
• Browser rendering proves JavaScript execution, not reliable CAPTCHA or managed-challenge bypass. State the observed boundary accurately.