AlexandrAI AGENTS.md
agents-md

FileGraph Source-Aware Ingest API Agent Guide

Agent guide for FileGraph ingest routes and their source identity contract.

AGENTS.md

Guidance for coding agents working on FileGraph Source-Aware Ingest API in the FileGraph project.

Project overview

This guide covers src/app/api/ingest/notes/route.ts, src/app/api/ingest/notes/batch/route.ts, and the ingest paths inside src/lib/filegraph/service.ts. The ingest API accepts external source records, validates them with zod, upserts notes by origin identity, and returns async analysis metadata without waiting for the analyzer to finish.

Primary source files

  • src/app/api/ingest/notes/route.ts validates one item and calls service.ingestNote.
  • src/app/api/ingest/notes/batch/route.ts validates an items array and calls service.ingestBatch.
  • src/lib/filegraph/service.ts implements ingestNote, ingestBatch, persistNote, sourceIndex, and job queueing.
  • src/lib/filegraph/types.ts defines IngestNotePayload, NoteOrigin, IngestJobResult, and IngestStatus.
  • src/app/api/ingest/notes/route.test.ts verifies the route returns queued job metadata.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Keep route validation strict: title and contentMarkdown are required, origin.kind is manual or confluence, and externalId is required.
  • Treat origin.kind plus origin.externalId as the stable source identity for dedupe and updates.
  • Return created, updated, unchanged, or rejected from service methods; do not collapse all outcomes into a generic success flag.
  • Batch ingest should keep processing after an item fails and return a per-item rejected result.
  • Preserve hints.tags and hints.parentExternalIds as analyzer input, not as trusted final metadata.
  • Do not make the API route wait for analysis completion; it should enqueue and return analysisStatus queued with a job id when content changed.
  • Keep sourceUrl as nullable metadata. Do not require it, and do not expose sample source URLs in public docs or fixtures.
  • When changing route schemas, update types, tests, and any sync client code together.

Testing

Test malformed payloads, missing external ids, single ingest creation, repeated unchanged ingest, revision updates, batch partial rejection, parentExternalIds mapping through sourceIndex, and async job metadata. Use setFileGraphServiceForTesting with a fake analyzer so route tests are deterministic.

PR checklist

  • Route tests pass without real network or CLI dependencies.
  • Repeated external source sync preserves note id.
  • Batch results keep input order.
  • No fixture includes a real host, source URL, or local path.