AlexandrAI AGENTS.md
agents-md

FileGraph Markdown Workbench Agent Guide

Agent guide for the FileGraph editor-first workbench, markdown toolbar, preview, and analysis polling flow.

AGENTS.md

Guidance for coding agents working on FileGraph Markdown Workbench in the FileGraph project.

Project overview

This guide covers src/components/filegraph-app.tsx and src/components/markdown-editor.tsx. The workbench loads initial notes and graph data from the server page, lets users filter notes, edit markdown, preview with GFM rendering, save or reanalyze notes, track queued analysis until settled, and switch into graph mode when needed.

Primary source files

  • src/app/page.tsx fetches notes and graph from the service and passes serialized notes into FileGraphApp.
  • src/components/filegraph-app.tsx owns notes tab, graph tab, save flow, reanalyze flow, polling, status messages, and side panels.
  • src/components/markdown-editor.tsx wraps CodeMirror and exposes applyAction plus focus through a ref.
  • src/lib/filegraph/api.ts serializes StoredNote metadata and body into NoteResponse.
  • src/components/filegraph-app.test.tsx covers workspace rendering, toolbar snippets, idle polling, and reanalyze polling.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Keep idle workbench quiet; tests assert it does not poll notes or graph while nothing is queued.
  • Save should POST to notes for new drafts and PUT to the selected note path for existing notes.
  • After save or reanalyze, refresh the specific note first and poll only while analysisStatus is queued or running.
  • Refresh the graph when analysis settles so sidebars and canvas reflect new relations and communities.
  • Keep MarkdownEditor actions pure text insertions and support jsdom through the textarea fallback.
  • Do not introduce source editing for imported origin fields in the markdown UI unless service update semantics are changed too.
  • Preserve preview rendering through ReactMarkdown with GFM support so toolbar snippets are immediately visible.
  • When changing NoteResponse fields, update serializer, app state usage, and tests together.

Testing

Test toolbar insertions, selection replacement, jsdom textarea behavior, save route selection, reanalyze route call, queued-to-ready polling, no idle polling, note filtering, graph switching, selected note metadata, and markdown preview output.

PR checklist

  • filegraph-app tests pass.
  • Saving a draft updates local state and graph state when analysis finishes.
  • Toolbar actions still work in jsdom and in CodeMirror.
  • No UI path leaks local file paths or private service addresses.