arxiv-sanity-mcp: Instructions file for Codex

AGENTS.md

This file defines how agents should work in this repository during the bootstrap phase.

Mission

Help build an MCP-native research discovery substrate inspired by arxiv-sanity, while preserving the most important product values:

• discovery over overload,
• explicit and steerable taste / interest modeling,
• fast browse / triage loops,
• recent-paper monitoring,
• and inspectable ranking and provenance.

Do not do these things

Do not:

• assume tags are the final or canonical taste representation,
• assume dense retrieval is obviously the winner,
• assume lexical retrieval is obsolete,
• assume the first MCP interface should mirror a web UI,
• assume “paper chat” is the product,
• serve or redistribute full text without checking license / provenance implications,
• collapse open questions into hidden code assumptions.

Default working posture

Unless an ADR says otherwise:

1. keep the design space open,
2. prefer cheap defaults,
3. preserve reversibility,
4. record uncertainty explicitly,
5. separate hypotheses from decisions.

Project-specific anti-patterns to detect

Patterns this project has already drifted into once (the 005-008 spike chain is the canonical case). When you notice one, name it; surface it to a deliberation rather than working around it. Cite-back to LONG-ARC.md per pattern so duplication-drift between this section and the source is detectable on next-pass review.

• Tournament narrowing under "disciplined" framing (LONG-ARC.md:47). Sequentially pruning a candidate set toward a winner. Counter-posture: rank-and-deprioritize, not eliminate; multi-lens framing replaces winner-pick.
• Single-lens "interface" by accident (LONG-ARC.md:48). Shipping a lens abstraction alongside only one lens — the abstraction ends up shaped exactly to that lens. Counter-posture: validate abstractions by shipping a second implementation, per ADR-0005.
• Silent defaults (LONG-ARC.md:49). A reference frame becomes the implicit baseline that all alternatives are measured against, even when nothing argued for it being baseline. Counter-posture: name the reference frame explicitly; require challengers measured against multiple frames or task outcomes.
• ADR violation by gradual local-reasonable steps (LONG-ARC.md:50). Each step locally defensible; cumulative drift away from an accepted ADR. Counter-posture: run an ADR-against-current-work check at deliberation boundaries (see below); ADRs are read at planning time, not just at writing time.
• Closure pressure at every layer (LONG-ARC.md:51). Confident remedies, prescriptive language, calibrated language reserved for closing footnotes. Counter-posture: calibrated language as default register; flag confident-sounding remedies for paired review before adoption (see METHODOLOGY.md:104-115, M1).
• Embedding-model choice as load-bearing decision (LONG-ARC.md:52). Treating "which model wins" as the architectural commitment when most leverage lives upstream. Counter-posture: treat embedding-model selection as one lens-design decision among many.
• Single-reader framing claims as authoritative (LONG-ARC.md:53). Audit memos and framing critiques produced by one reader propagated as ground truth. Counter-posture: paired review for framing claims (cross-vendor + same-vendor); consult METHODOLOGY.md (M1 status: Hypothesis as of 2026-04-26 update at line 119).