docgraph: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Claude Code, opencode, and others) working in this repository. CLAUDE.md is a symlink to this file so every agent shares one source of truth.

Golden rule — commits

Never commit or push anything to git without co-authorship attribution. Every commit created with AI assistance MUST include a trailer identifying the assisting agent.

Do not use --no-verify, do not skip hooks, and do not force-push unless the maintainer explicitly asks. Only commit or push when the user requests it.

What this project is

DocGraph is a universal documentation knowledge-graph MCP server with hybrid full-text (SQLite FTS5) + vector search. It ships a CLI and an MCP server and is designed to run as a local MCP server inside a repository.

Commands

npm install        # install dependencies
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check without emitting
npm test           # compile tests (tsconfig.test.json) and run node:test

Always run npm run typecheck and npm test before proposing a commit.

Architecture (Clean Architecture)

Dependencies point inward. Never let an inner layer import an outer one.

• src/domain/ — entities, ports (interfaces), pure services. Depends on nothing.
• src/application/ — use cases (IndexingService, SearchService, QueryService). Depends only on domain.
• src/infrastructure/ — adapters implementing domain ports (SQLite, embeddings, filesystem, config). Depends on domain.
• src/presentation/ — entry points (CLI, MCP server).
• src/container.ts — the composition root; the only place that instantiates concrete adapters. Wire new dependencies here.

When adding a feature: define/extend a port in domain, implement the adapter in infrastructure, orchestrate it in an application service, and wire it in container.ts.

Cross-platform & path rules

This tool must run on any OS and is meant to be embedded as a local MCP server.