AlexandrAI AGENTS.md
agents-md

FileGraph Agent Guide

Project-specific AGENTS.md guidance for the FileGraph local-first markdown graph app, covering vault metadata, ingestion, analyzer fallback, API routes, tests, and UI rules.

AGENTS.md

Guidance for coding agents working on FileGraph, a local-first markdown note app with graph-aware metadata, source-aware ingestion, and asynchronous note analysis.

Project Overview

FileGraph stores notes as markdown files under vault/notes/ and writes derived graph artifacts under vault/.filegraph/. Each note file starts with a comment-wrapped FILEGRAPH_META_V1 JSON block followed by the markdown body. The service rebuilds graph, source index, search index, catalog, taxonomy, communities, and master metadata artifacts from that vault state.

The app is a Next.js project. Its local service layer is the source of truth for note persistence and graph artifacts; the web UI should call API routes rather than writing vault files directly.

Repository Map

  • src/lib/filegraph/service.ts: main FileGraphService; note create/update/upsert, vault rescans, graph artifacts, search, queue processing, retrieval context.
  • src/lib/filegraph/analyzer.ts: Claude CLI analyzer, heuristic fallback analyzer, strict prompt rules, structured JSON extraction.
  • src/lib/filegraph/metadata.ts: builds and parses the FILEGRAPH_META_V1 markdown document format.
  • src/lib/filegraph/types.ts: note, relation, graph, taxonomy, ingestion, retrieval, and analyzer contracts.
  • src/lib/filegraph/api.ts: API serialization helpers.
  • src/lib/filegraph/service-instance.ts: singleton service wiring and testing override.
  • src/app/api/**/route.ts: notes, ingest, graph, retrieval context, reanalyze, and rescan endpoints.
  • src/components/filegraph-app.tsx: editor-first workbench UI.
  • src/components/graph-canvas.tsx: graph rendering.
  • src/components/markdown-editor.tsx: markdown editing controls.
  • vault/notes/: runtime note files. Keep real content out of public reports.
  • vault/.filegraph/: generated runtime artifacts. Do not hand-edit.

Setup Commands

bashpnpm install
pnpm dev
pnpm lint
pnpm test
pnpm build

The dev and start scripts bind the Next server to a loopback host and port declared in package.json. Avoid publishing private vault content, runtime URLs, or local machine paths in public artifacts.

Verified This Run

These commands passed on 2026-06-29:

bashpnpm test
pnpm lint

The test run reported 6 files and 13 tests passing. Lint completed with no reported errors.

Architecture Rules

  • Keep vault persistence in FileGraphService; do not duplicate filesystem writes in API routes or UI components.
  • Keep note files round-trippable through buildNoteDocument() and parseNoteDocument().
  • Preserve the FILEGRAPH_META_V1 header format unless you also add a schema migration plan.
  • Keep runtime notes and generated graph artifacts out of git and out of public archive items.
  • Treat vault/notes/ content as sensitive, even when it is markdown.
  • Keep source-aware upsert identity stable through origin.kind plus origin.externalId.
  • Use waitForIdle() in tests when assertions depend on asynchronous analysis.
  • Keep enableWatcher: false in deterministic service tests.

Analyzer Rules

The analyzer path has two modes:

  • ClaudeCliAnalyzer calls the local claude CLI and expects structured JSON.
  • HeuristicAnalyzer keeps the graph usable when Claude CLI is unavailable or returns invalid output.

When editing analyzer behavior:

  • Keep the prompt's JSON-only contract.
  • Do not let analysis output reference note IDs outside the candidate set.
  • Do not let a note reference itself as parent, child, or related.
  • Keep tags, entity types, and community hints constrained to the generated taxonomy guide.
  • Keep fallback output deterministic enough for tests.
  • Do not log raw note bodies or full prompts in production paths.

Service Invariants

  • Manual notes use origin.kind = "manual".
  • Ingested Confluence notes use origin.kind = "confluence" and stable external IDs.
  • Unchanged upserts should return status: "unchanged" and keep the same note ID.
  • Updated source content should keep the same note ID when the origin identity is unchanged.
  • Analysis status should progress through queued/running/ready or error.
  • Relation proposals must be resolved only to known notes.
  • Graph edges should derive from note relations and preserve relation reasons and shared entities.
  • Search and retrieval context should use graph neighbors and same-source-space neighbors, not only raw text search.
  • rescanVault() must rebuild in-memory state from note files and regenerate artifacts.

API Contract Notes

  • GET /api/notes returns serialized notes.
  • POST /api/notes creates manual notes from title and markdown body.
  • GET /api/notes/:id returns one note or a 404-shaped error.
  • PUT /api/notes/:id updates a manual note and queues analysis.
  • POST /api/notes/:id/reanalyze queues analysis for an existing note.
  • POST /api/ingest/notes upserts one source-aware note.
  • POST /api/ingest/notes/batch upserts multiple notes and returns per-item results.
  • GET /api/graph returns the current graph snapshot.
  • GET /api/retrieval/context returns seed notes, neighbors, communities, and markdown context.
  • POST /api/vault/rescan rebuilds service state from vault files.

Validate inputs with Zod at the route boundary. Keep route handlers thin and delegate behavior to the service.

Testing Rules

Run focused tests for any touched layer:

bashpnpm test -- src/lib/filegraph/service.test.ts
pnpm test -- src/lib/filegraph/analyzer.test.ts
pnpm test -- src/lib/filegraph/metadata.test.ts
pnpm test -- src/app/api/notes/route.test.ts
pnpm test -- src/app/api/ingest/notes/route.test.ts
pnpm test -- src/components/filegraph-app.test.tsx

Use temporary directories and fake analyzers in service/API tests. Do not use a real vault or the real Claude CLI in deterministic tests.

UI Rules

  • Keep the workbench editor-first and compact.
  • Preserve accessible labels for note title, markdown editor, tabs, and toolbar actions.
  • Avoid global polling while the app is idle; tests assert that idle polling does not happen.
  • After reanalysis, refresh the specific note/job path rather than polling everything.
  • Keep graph mode and notes mode as explicit tabs.
  • Use existing components and icon patterns before adding new UI dependencies.

Change Checklist

  • For metadata format changes: update types.ts, metadata.ts, service rebuild behavior, and round-trip tests.
  • For ingestion changes: update Zod schemas, source identity behavior, batch behavior, and route tests.
  • For analyzer changes: update prompt tests, fallback tests, and relation resolution expectations.
  • For graph changes: update service tests for edges, communities, catalog, taxonomy, and master metadata.
  • For UI changes: update component tests and preserve accessible roles/labels.
  • Before publishing or handing off: run pnpm lint and pnpm test.