TableRAG: Instructions file for Codex

TableRAG MCP Agent Notes

• Source discovery is non-recursive by default. Do not index subfolders unless the project YAML explicitly sets recursive: true; root-only discovery and a 413-file real build verified this boundary.
• Keep the Python MCP SDK below major version 2 until the FastMCP server and protocol tests are deliberately migrated. Allowing an unconstrained mcp>=1.10 installed an incompatible 2.0 API; mcp>=1.10,<2.0 passed in-memory, real stdio, and Streamable HTTP calls.
• On Windows, replace the local Web server by resolving the listening PID with netstat and verifying the localhost page is TableRAG before stopping it. CIM and Get-NetTCPConnection process discovery hung on this host; the signature-checked replacement restarted port 8766 and the diagnostics status endpoint returned HTTP 200.
• On Windows, active stdio MCP clients can lock .venv\Scripts\table-rag.exe, causing uv run to fail while refreshing the editable install. Do not stop user MCP services for tests; run .venv\Scripts\python.exe -m pytest directly and use uv lock for lockfile-only updates. This path passed the full suite while four live MCP client processes remained running.
• Do not write large DuckDB index tables with Python executemany; use bounded vectorized bulk inserts and verify catalog counts. Replacing row-wise field-value writes produced 1,868,984 values from 413 real workbooks in 129.36 seconds, followed by a 1.54-second unchanged rebuild.
• DuckDB connections in one process must use the same read_only configuration. Web queries that overlap the index watcher use read-write connections with schema initialization disabled; the writer-overlap regression and 40 live /api/state requests passed without HTTP 400 responses.
• Repository checkouts may use the GitHub repository name as their folder. Tests for workspace identity must compare resolved repository roots, not a hard-coded checkout basename; the Windows/Linux CI matrix passed after the rename-safe assertion replaced table-rag-mcp.
• Bare mirror clones set remote.*.mirror=true, which rejects explicit refspecs and --force-with-lease. For leased history rewrites, add a separate non-mirror remote; the two-branch atomic cleanup push passed with that setup.