enquire-mcp: Instructions file for Codex

AGENTS.md

Notes for AI coding agents (Cursor, Claude Code, Codex, Aider, Devin, etc.) working in this repo.

You are NOT a user. Users invoke enquire-mcp via MCP from their AI agents. This file is for AI agents modifying enquire-mcp's source code (PRs, refactors, bug fixes). For end-user docs see README.md and docs/.

TL;DR

• Production code: src/*.ts (TypeScript strict + noUncheckedIndexedAccess)
• Tests: tests/*.test.ts (Vitest, 2272+ tests)
• Build: npm run build (tsc → dist/)
• Test: npm test (full unit + compiled-dist suite; duration is hardware-dependent)
• Lint: npm run lint (biome — must exit 0)
• Coverage: npm run test:coverage (13 per-file coverage floors enforced)
• Audit: npm run check:audit (source + published-consumer dependency graphs)
• OIA: npm run check:oia (state-driven drift scan — 12 checks)
• Version sync: node scripts/check-version-consistency.mjs

release.yml directly enumerates the 13 release-required CI checks listed below, all of which run on every PR. Branch protection now enforces all 13 directly enumerated contexts (live snapshot verified 2026-08-21). The protected test (22) context runs exactly Node 22.13.0, the literal engines.node floor; its explicit matrix label must not change. The pinned test-windows hostile-filesystem and startup-interlock job is an additional named check-run enforced transitively as a blocking prerequisite of smoke, so a Windows failure must make smoke fail rather than skip. The package-consumer context aggregates blocking Linux, Windows, and macOS packed-install lanes; mcpb-basic consumes one exact Linux-built bundle on those same three systems. Local checks above must pass before pushing.

Architecture (5-minute orientation)

src/
├── cli.ts              — commander.js CLI (subcommands: serve, serve-http, first-run, setup, configure, install-model, build-embeddings, index, doctor, eval, eval-compare, install-ocr-lang, gen-token, clear-cache, clear-feedback, clear-index, clear-embeddings, query, prune)
├── cli-help.ts         — shared CLI help-text constants (drift-prevention; see "Help text rule" below)
├── first-run.ts        — deterministic preview/apply onboarding plan + stop/resume executor
├── server.ts           — MCP server bootstrap + dependency wiring
├── mcp-registration.ts — SDK-agnostic gated registration facade (no server monkey-patch)
├── initialize-instructions.ts — configuration-aware, byte-bounded MCP handshake guidance
├── tool-registry.ts    — tool registration manifest
├── tool-manifest.ts    — tool metadata (names, schemas, readOnlyHint)
├── prompts.ts          — 19 MCP prompts
├── tools/              — 47 tool implementations (read, write, search, media, meta)
├── vault.ts            — Obsidian vault filesystem layer + privacy filter
├── fts5.ts             — SQLite FTS5 BM25 index
├── embed-db.ts         — embedding storage (int8-quantized BLOBs)
├── embeddings.ts       — Hugging Face transformer.js loader
├── embed-pipeline.ts   — chunking + embedding build pipeline
├── embed-sync.ts       — bulk embedding sync (fail-soft runtime / strict evidence mode)
├── hnsw.ts             — HNSW vector index wrapper
├── rrf.ts              — reciprocal-rank-fusion (orchestration in tools/search.ts)
├── watcher.ts          — chokidar filesystem watcher → incremental re-index
├── http-transport.ts   — streamable HTTP MCP transport (Express)
├── bases.ts            — Obsidian Bases DSL parser + executor
└── doctor.ts           — health check (color-coded ✓/⚠/✗)

scripts/
├── oia-walk.mjs                       — state-driven drift scan (12 checks)
├── build-pages.mjs                    — deterministic Pages landing + TypeDoc composite
├── check-per-file-coverage.mjs        — per-file branch floor enforcement
├── check-version-consistency.mjs      — version sync across 8 surfaces
├── check-changelog-coverage.mjs       — CHANGELOG claims vs reality

tests/
├── *.test.ts                          — Vitest unit tests
├── docs-consistency.test.ts           — invariant: README/package.json claims match reality
├── cli-parity.test.ts                 — invariant: serve and serve-http have identical shared-flag help text
├── k1-class-invariant.test.ts         — structural guard for the K-1 saga
└── ...

docs/
├── api.md              — tool catalog
├── COMPARISON.md       — TOP-1 product case + evidence-bound proof surface
├── QUICKSTART.md       — onboarding
├── benchmarks.md       — retrieval-quality benchmarks
├── http-transport.md   — remote MCP transport guide
└── api-reference/      — auto-generated TypeDoc (do NOT edit by hand)

site/                   — version-controlled GitHub Pages landing source