graph-atlas-mcp: Instructions file for Claude Code

Working in this repo

Commits and PRs

• Never add Co-Authored-By: trailers to commit messages, and never add "Generated with …" attribution lines to PR descriptions. Commit messages end at the last body paragraph.
• Branch for changes and open a PR; main is merged through review.

Two release channels — do not conflate them

This repo publishes on two independent channels, and confusing them has already caused one production incident:

Channel	Tag format	Carries	Created by
Data — snapshot database	v2026.08.11 (calendar)	graph-atlas.db.gz asset	collect.yml → scripts/create-release.js, daily when changes are detected
Server — npm package	v0.3.1 (semver)	no assets	publish.yml, manually dispatched

Never use GitHub's /releases/latest (or a bare gh release download) to find the database. That endpoint returns whichever release published most recently, which is a semver server release whenever an npm publish lands after that day's data release — and those carry no database asset. Resolve the newest calendar-tagged release explicitly:

• TypeScript: fetchLatestDataRelease() in src/github-releases.ts
• Workflows: gh release list --json tagName --jq filtered on ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}$

Failing to restore an existing database is not the same as "no database exists yet". scripts/collect-and-diff.js reads its diff baseline from the committed snapshots/ directory, not from the database, so a run that starts from an empty database still detects changes and publishes them — releasing a database stripped of all history, permissions, roles and embeddings over a good one. Fail loudly rather than starting fresh.

Known gaps

Both rules above are enforced on the paths that caused the original incident, but an audit found these still open. They are recorded rather than fixed so they aren't rediscovered from scratch; treat them as live hazards when touching the release path.