AlexandrAI AGENTS.md
agents-md

FileGraph Agent Guide

Project-specific AGENTS.md guidance for the FileGraph local-first markdown graph workbench.

AGENTS.md

Guidance for coding agents working on FileGraph. Humans read README.md; this guide keeps the project-specific operating detail an agent needs.

Project Overview

FileGraph is a local-first markdown notes workbench with graph-aware metadata. Notes live under vault/notes/, derived graph artifacts live under vault/.filegraph/, and the UI can edit notes directly while also accepting source-aware HTTP upserts for external ingestion.

The application is a Next.js 16 / React 19 TypeScript app. It uses CodeMirror for markdown editing, Cytoscape for graph visualization, MiniSearch for retrieval, Zod for validation, Vitest for tests, and a local Claude CLI when available for asynchronous metadata enrichment. If Claude is unavailable, the graph remains usable through a heuristic analyzer.

Setup Commands

bashpnpm install
pnpm dev
pnpm lint
pnpm test
pnpm build

Run commands from the repository root. Do not publish or hard-code local machine paths or local URLs with private ports in examples; use repo-relative paths such as vault/notes and neutral placeholders.

Main Surfaces

  • src/app/page.tsx: primary app entry.
  • src/components/filegraph-app.tsx: main workbench component.
  • src/components/markdown-editor.tsx: editor surface.
  • src/components/graph-canvas.tsx: graph rendering.
  • src/components/filegraph-app.test.tsx: UI-level behavior tests.
  • vault/notes/: runtime markdown notes; treat as user data.
  • vault/.filegraph/: derived catalog, graph, search, source, and taxonomy artifacts.

API Shape

The README documents the important route families:

  • Notes: GET/POST /api/notes, GET/PUT /api/notes/:id, POST /api/notes/:id/reanalyze
  • Ingest: POST /api/ingest/notes, POST /api/ingest/notes/batch
  • Graph and retrieval: GET /api/graph, GET /api/retrieval/context
  • Maintenance: POST /api/vault/rescan

Keep route behavior source-aware. Ingested notes should preserve origin identity, external ids, source URLs, revision hints, and parent references where the schema supports them.

Code Style

  • Preserve the local-first model: markdown files are the durable note body; derived graph files are rebuildable.
  • Keep metadata parsing strict enough to protect the graph index, but resilient enough that a malformed note does not take down the workbench.
  • Keep UI state and file persistence boundaries clear. UI edits should become direct note updates, not hidden derived-state mutations.
  • Prefer existing helpers and Zod schemas before adding new validators.
  • Do not commit generated runtime notes or graph artifacts unless the task explicitly says the fixture belongs in source control.

Testing

Use the focused command first:

bashpnpm test

For UI changes, add or update Vitest tests near src/components/filegraph-app.test.tsx or the nearest affected component. For route/service changes, test the parser, graph rebuild, source-aware ingest, and fallback analyzer behavior that the change touches. Run pnpm lint and pnpm build before claiming a broad UI or route change is complete.

Security And Privacy

  • Treat note contents as local user data.
  • Never publish local absolute paths, private URLs, tokens, credentials, or raw environment values.
  • Do not assume source URLs are safe to render without sanitizing or escaping.
  • Keep any LLM-enriched summaries distinguishable from human-authored note content.

Commit And PR Rules

  • Keep changes narrow: UI, route, analyzer, and graph index changes should be separable unless the task requires an end-to-end flow.
  • Document any migration of note metadata format.
  • If a change affects derived graph artifacts, state whether users need a rescan.