docs: CLAUDE.md + AGENTS.md describe a Python agent runtime that doesn't exist — real backend is TypeScript in app/lib/

[jravinder]

Problem

CLAUDE.md and AGENTS.md both describe TXLookup as a Python async agent in agent/main.py orchestrating tools through agent/executor.py with state in agent/memory.py. New contributors (and AI agents — this skill just hit it) read those docs first and waste context inferring an architecture that isn't shipped.

The actual runtime:

• The live agent loop is TypeScript in app/lib/agent.ts (1348 lines), called from app/api/agent/route.ts as an SSE stream
• Specialists live in app/lib/specialists.ts (898 lines), not agent/specialists/*.py
• Doom-loop guard is app/lib/doomLoop.ts (the Python agent/doom_loop.py is the historical port)
• agent/main.py, agent/executor.py, agent/memory.py are all skeletons full of # TODO: Codex — placeholders and aren't imported anywhere

What IS still Python and load-bearing:

• agent/planner.py (484 lines, used by mcp/server.py + tests)
• agent/tools/data.py (Socrata client, used by mcp/server.py)
• agent/tools/miro.py (used by mcp/server.py)
• agent/specialists/dataset_scout.py + ingestor.py (cron workers via .github/workflows/)

Fix

Rewrite the "Quick Context", "Key Files", and "Architecture" sections of both docs to reflect reality:

• Frontend + agent runtime + API: TypeScript in app/
• MCP surface + cron workers (scout, ingestor): Python in agent/ + mcp/
• Source-of-truth files: app/lib/agent.ts, app/lib/specialists.ts, app/lib/doomLoop.ts, app/api/agent/route.ts, agent/planner.py, agent/specialists/, mcp/server.py

Drop agent/main.py from the key-files table or mark it explicitly as historical.

Code pointers

• CLAUDE.md:13-19, 60-72 — the misleading sections
• AGENTS.md:14-22, 32-77 — same drift
• app/lib/agent.ts, app/lib/specialists.ts — actual runtime
• agent/main.py, agent/executor.py, agent/memory.py — stubs to flag

Acceptance

• CLAUDE.md + AGENTS.md accurately point new contributors at app/lib/agent.ts for the agent loop
• Python files that ARE live (planner, data, miro, scout, ingestor, mcp) are still listed
• Stub Python files are marked or removed (see paired dead-code issue)