grandstack
docs / grandstack / Agents

AGENTS.md: guide for coding agents

Compose stack plus the overview docs for GRANDstack (GraphQL on Neo4j: grandstack-server, grandstack-web). Read docs/agents.md first; it covers the mental model, where to change what, the verification checklist and the gotchas. llms.txt indexes everything.

  • Start: cp .env.example .env && docker compose up --build (web :3000, GraphQL :4000/graphql, Neo4j :7474). The three repos must sit side by side because compose builds from ../grandstack-server and ../grandstack-web.

  • docker compose down -v deletes the Neo4j data; the sample reseeds on the next start.

  • Change the schema, seed or server behaviour in grandstack-server; change the UI in grandstack-web; follow each repo’s AGENTS.md and docs/recipes.md.

  • Before you finish, run the checks for each repo you changed (listed in docs/agents.md) and node scripts/check-links.mjs here.

  • The default stack has no authentication. The opt-in auth setup (docker compose -f compose.yaml -f compose.auth.yaml up --build, from the grandstack-auth repo) is development-only. Do not expose either publicly.

  • Agents: docker compose -f compose.yaml -f compose.agents.yaml up --build adds an MCP server at http://localhost:4100/mcp (from the grandstack-agents repo). It is read-only unless AGENTS_ALLOW_MUTATIONS=true, has no auth of its own, and talks to the open server. Keep it local.

  • Federation: docker compose -f compose.yaml -f compose.federation.yaml up --build (from the grandstack-federation repo) puts a gateway on :4000 and moves the server subgraph to :4001; a Wikipedia subgraph adds summaries to films and people. Needs internet. It replaces the other setups on port 4000. Open, no auth.

  • Keep docs true: update the doc next to the behaviour you change, in the same change.

  • Diagrams: docs/diagrams/*.svg are hand-written SVG with numbered callouts, each embedded with a numbered text legend. When you change the behaviour a diagram shows, edit the SVG and its legend in the same change; node scripts/check-links.mjs fails if an image has no alt text, an SVG contains script or style, or the legend numbers differ from the callouts drawn.

  • New code files need the copyright header (two lines: Copyright (c) "Neo4j" and Neo4j Sweden AB [http://neo4j.com], in the file’s comment syntax). Run node ../grandstack/scripts/add-headers.mjs to add it everywhere; --check lists what is missing. Generated files are exempt.

  • Releases use the release-cut workflow (Actions tab), which sets the version in every package.json, tags and publishes. Do not bump versions or push tags by hand; see grandstack/docs/releasing.md.

Source: grandstack/AGENTS.md (this page is a copy; edit it in the repository)