pitlane-mcp: Instructions file for Codex

Pitlane MCP Usage

Use pitlane-mcp for code lookup whenever it is available.

Default public tier:

• ensure_project_ready
• investigate
• locate_code
• read_code_unit
• trace_path
• analyze_impact
• analyze_changes
• get_index_changes
• get_index_stats
• doctor
• server_info
• search_content
• search_knowledge
• read_knowledge_document

Advanced primitive tools are hidden from tools/list unless the server is started with PITLANE_MCP_TOOL_TIER=all.

Startup

1. Prefer ensure_project_ready for normal startup. It ensures the index exists and reports whether embeddings are still running, but it does not block on embeddings.
2. Use investigate as the first tool for broad code questions such as subsystem, behavior, and execution-path questions.
3. If you explicitly exposed the advanced tool tier and use index_project directly, call wait_for_embeddings immediately when it returns embeddings="running". Do not poll get_index_stats to wait.
4. Call watch_project only when you explicitly exposed advanced tools and expect the repo to change during the session.

Navigation

1. Use investigate for broad code questions when you want the server to discover symbols and inline the relevant source in one call.
2. Use locate_code when the user wants to find code but it is not yet clear whether the target is a symbol, file, or text fragment.
3. Use read_code_unit once you know the target and want the smallest useful read instead of manually choosing between lower-level read primitives.
4. Use trace_path for behavior, source-to-sink, config-to-effect, shortest-path, and other execution-path questions.
5. Use analyze_impact for blast-radius questions before edits or refactors. Use analyze_changes to map a Git diff to revision-qualified symbols, impact evidence, and test candidates.
6. Use search_content when you know a text snippet, log string, import path, macro name, or regex fragment but do not know the symbol boundary yet.
7. Use search_knowledge for documentation questions — it searches indexed Markdown (docs, READMEs, runbooks) by heading and content, with hybrid lexical/semantic ranking when embeddings exist. It understands OKF v0.2 documents natively: filter by concept type/status/trust tier via okf_type/status/min_trust, and results carry trust, staleness, and cross-document related_docs relationships.
8. Use read_knowledge_document to open a document found by search_knowledge: the full source Markdown by default, or one section via section (a sections[].section_id slug or the full section_id). Results include OKF metadata, the section outline with line ranges, and the link graph (related_docs outgoing, referenced_by incoming).
9. Use get_index_stats to orient yourself in unfamiliar repos before broader exploration.
10. Fall back to direct file reads only when editing or when full-file context is genuinely required.
11. Treat read_code_unit as the preferred diff-aware read surface. Use its read_state.status field to decide whether to reuse the payload, expand, or reread: new means first read in this session unchanged means the same target was reread with identical content, so expand instead of rereading again changed means the same target changed since the previous read, so use the refreshed payload before expanding
12. When locate_code, trace_path, or analyze_impact return session_state, use it to understand whether the top target was already seen and whether the server intentionally promoted an unseen nearby alternative.