AlexandrAI AGENTS.md
agents-md

FileGraph Metadata Header Agent Guide

Agent guide for FileGraph comment-wrapped metadata headers in markdown notes.

AGENTS.md

Guidance for coding agents working on FileGraph Metadata Header in the FileGraph project.

Project overview

This guide covers src/lib/filegraph/metadata.ts and the NoteFrontmatter contract in src/lib/filegraph/types.ts. Each stored note is a markdown body preceded by a comment-wrapped JSON metadata block. The parser requires the block at the start of the file, and the builder round-trips metadata plus body without rewriting the markdown content.

Primary source files

  • src/lib/filegraph/metadata.ts defines HEADER_START, HEADER_END, buildNoteDocument, and parseNoteDocument.
  • src/lib/filegraph/types.ts defines NoteFrontmatter, NoteRelation, NoteEntity, OriginKind, AnalysisStatus, and StoredNote.
  • src/lib/filegraph/service.ts calls buildNoteDocument for note writes and parseNoteDocument during rescanVault.
  • src/lib/filegraph/metadata.test.ts verifies round-trip behavior and missing-header failures.

Setup commands

pnpm install pnpm test pnpm lint pnpm build

Change rules

  • Keep the metadata block as the first bytes of the document so rescanVault can parse notes deterministically.
  • Do not switch to YAML frontmatter unless every parser, test, existing note, and migration path is changed together.
  • Preserve schemaVersion, noteId, title, slug, createdAt, updatedAt, sourceHash, analysisStatus, analysisVersion, analysisJobId, origin, relations, and error fields.
  • Keep the markdown body separate from generated metadata; user-authored note text must not be polluted with analysis fields.
  • Throw clearly when the required metadata marker is missing so malformed files do not silently enter the graph.
  • Do not publish stored notes with real sourceUrl values or local file paths when preparing external documentation.
  • When adding metadata fields, update NoteFrontmatter, builder tests, service persistence, serializers, and any UI readers together.
  • Keep body trailing newline handling in service code, not in the parser, so parsing remains a faithful read.

Testing

Test exact round trip, body preservation, missing header, invalid JSON, added optional fields, relation arrays, origin records, and legacy or malformed note handling. For service changes, also test rescanVault because it is the path that rehydrates notes from disk.

PR checklist

  • metadata.test.ts passes.
  • Existing notes can still be parsed after schema changes.
  • New fields are documented in types and serializers.
  • No generated guide includes real source URLs or local filesystem paths.